gitpane 1.0.0__py3-none-any.whl

gitpane/config.py

@@ -0,0 +1,1066 @@
+"""Definitions that several GitPane modules must agree on, from shared values to the sizing rules of controls."""
+
+from __future__ import annotations
+
+import posixpath
+from dataclasses import dataclass
+from enum import Enum, IntEnum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from PySide6.QtCore import QMargins, QPoint, QRect
+    from PySide6.QtGui import QScreen
+    from PySide6.QtWidgets import QWidget
+
+# Start of the names of the trace variables of Git and of the Git Credential Manager. Every place that removes traces
+# from the environment of a program it starts reads this one value.
+TRACE_ENVIRONMENT_PREFIXES = ("GIT_TRACE", "GCM_TRACE")
+# Variables of GitPane itself and of Git or credential manager traces: a text editor GitPane starts to open a working
+# copy file must not inherit them.
+EDITOR_HIDDEN_ENVIRONMENT_PREFIXES = ("GITPANE_", *TRACE_ENVIRONMENT_PREFIXES)
+ERROR_LIGHT_COLOR = "#b42318"
+ERROR_DARK_COLOR = "#ff8a80"
+# Green of a successful result, such as a Settings save, readable on a light or on a dark background.
+SUCCESS_LIGHT_COLOR = "#1a7f37"
+SUCCESS_DARK_COLOR = "#7ee2a8"
+# Orange of a result that is not an error but asks to switch to another method (a server that refuses passwords, for
+# example). Each keeps a contrast of at least 4.5:1 with its theme's background and stays clearly apart from the red.
+WARNING_LIGHT_COLOR = "#b45309"
+WARNING_DARK_COLOR = "#fdba74"
+# Yellow of a recent folder whose check got no answer (Unknown): apart from the grey path, so it is noticed, and from the
+# orange of Unavailable, so it is not read as gone. A dark gold on light backgrounds and a bright yellow on dark ones,
+# each with a contrast of at least 4.5:1.
+UNKNOWN_LIGHT_COLOR = "#8a6d00"
+UNKNOWN_DARK_COLOR = "#fde047"
+DARK_BACKGROUND_LIGHTNESS_LIMIT = 0.5
+EDITOR_CONNECT_TIMEOUT_MS = 5000
+EDITOR_LIVENESS_TIMEOUT_MS = 5000
+EDITOR_HEARTBEAT_INTERVAL_MS = 250
+# How long GitPane keeps a connection it answered open, for the bridge to read the answer and close it itself; past
+# this delay, GitPane closes it.
+EDITOR_ANSWERED_CLOSE_TIMEOUT_MS = 5000
+EDITOR_IPC_LIMIT_BYTES = 65536
+EDITOR_PENDING_LIMIT = 4
+EDITOR_REQUEST_LIMIT = 1024
+EDITOR_TOKEN_BYTES = 32
+
+# The longest a size change asked just after a window is shown waits for the compositor to answer that show (the
+# activation delivered to the window, and the configure that comes with it applied by Qt). Mutter answers in 8 to 15 ms,
+# and Qt applies that configure at the end of the frame in progress; a window it never activates (opened while the user
+# is in another application) still gets its size change once this bound is reached.
+COMPOSITOR_ANSWER_TIMEOUT_MS = 1_000
+# The longest one click waits, on the window's thread, for the Wayland compositor while GitPane asks for an activation
+# token: binding the protocol the first time, the window that has the keyboard, then the token, all within this one
+# bound. Mutter answers within a millisecond; a compositor that does not answer leaves the program to start without a
+# token instead of freezing GitPane.
+WAYLAND_ACTIVATION_TOKEN_TIMEOUT_MS = 500
+# Longest activation token GitPane hands to a program; a longer one is refused. Mutter's tokens are about 45
+# characters long (a UUID, "_TIME" and a time).
+ACTIVATION_TOKEN_MAX_LENGTH = 256
+# The longest each read of gnome-extensions may take when Settings checks whether GNOME can show desktop icons. The
+# tool answers in a few milliseconds; the bound only matters for a loaded session or a Shell that does not answer, and
+# a read with no answer in time gives no note rather than a wrong one.
+SHELL_EXTENSION_READ_TIMEOUT_MS = 3_000
+# The longest each of the three reads of the Secret Service may take when GitPane checks the default keyring collection.
+# Each read answers in about 0.5 ms; a read with no answer in time counts as an unknown state, which gives no sentence.
+KEYRING_READ_TIMEOUT_MS = 500
+# The longest the read of the desktop's light or dark preference may take, through the Settings portal, when GitPane
+# starts. The portal answers in under a millisecond; a read with no answer in time counts as no preference, which keeps
+# the appearance Qt shows without it.
+PORTAL_SETTING_READ_TIMEOUT_MS = 500
+# The longest the gitpane command typed in a terminal waits for GitPane, started again in a session of its own, to
+# show its first window before it gives the terminal back. A cold start on a slow disk takes a few seconds; past this
+# delay the command gives the terminal back and says so, and GitPane goes on starting without that terminal.
+DETACHED_READY_TIMEOUT_MS = 30_000
+# How long the gitpane command still reads a GitPane that closed its ready channel without the ready signal, then waits
+# for its end, counted from that close whatever is left of the wait above. A program GitPane started can keep its
+# output open after GitPane ended, and a process ends a little after its channel closes: past this delay the command
+# reports what it has and gives the terminal back.
+DETACHED_STOP_GRACE_MS = 5_000
+GIT_OPEN_TIMEOUT_MS = 5_000
+# Characters refused in any name or revision placed on a Git command line: none can belong to a reference name or
+# a revision, and each could split what Git or the logs receive.
+COMMAND_LINE_CONTROL_CHARACTER_SET = frozenset({"\0", "\n", "\r"})
+GIT_READ_TIMEOUT_MS = 30_000
+# The longest a reference form waits, unseen, for its opening check. That check runs at most two batches of Git
+# reads, each bounded by GIT_READ_TIMEOUT_MS, plus reads of reference files and its wait in the process queue: a slow
+# Git is still explained by its own error, and this limit only ends a check that never answers (an error the read
+# service does not catch, or a file read that blocks).
+FORM_OPENING_CHECK_TIMEOUT_MS = 3 * GIT_READ_TIMEOUT_MS
+# The whole history is read by one streamed process: a history of several hundred thousand commits can take a few
+# minutes to read and show. A Git that stops writing is still stopped much sooner by the ordinary inactivity limit.
+HISTORY_STREAM_TIMEOUT_MS = 600_000
+# While the history is read, its new rows are shown at most this often: the first rows appear at once, and the window
+# redraws a few times per second instead of once per chunk of Git output.
+HISTORY_PUBLISH_INTERVAL_MS = 200
+GIT_EXECUTABLE_PROBE_LIMIT_BYTES = 4096
+GIT_MUTATION_TIMEOUT_MS = 60_000
+TRASH_TIMEOUT_MS = 30_000
+GIT_COMMIT_TIMEOUT_MS = 120_000
+COMMIT_IDLE_TIMEOUT_MS = 120_000
+# The longest wait, from the click, before the --log timing of a commit stops with an "abandoned" line: a window whose
+# history never shows the commit must not be followed for the rest of the session. Well above the commit's own process
+# limit (GIT_COMMIT_TIMEOUT_MS), the refresh of a large repository and an ordinary push.
+COMMIT_TIMING_LIMIT_MS = 600_000
+MUTATION_IDLE_TIMEOUT_MS = 60_000
+# Placed in front of a native write command so it never descends into a submodule, even when the user set
+# submodule.recurse: a write of the parent repository must leave every file of every submodule untouched.
+SUBMODULE_RECURSION_OFF_ARGUMENTS = ("-c", "submodule.recurse=false")
+# Placed in front of the Git commands that write or verify a rewritten history. Under Windows, and under macOS on a
+# case-insensitive disk, git init writes core.ignorecase=true even in a bare repository, and fast-import then folds the
+# case of the paths it deletes: removing "Secret" also removes "SECRET". History removal compares recorded paths byte
+# for byte and never touches files on disk through these commands, so the case of a path must always count.
+EXACT_PATH_CASE_ARGUMENTS = ("-c", "core.ignorecase=false")
+# Where Git keeps every full reference name, and the namespaces under it of local branches, remote branches and tags.
+# They build the names and patterns given to Git (for-each-ref, refspecs) and read back what it lists.
+REFERENCE_ROOT_PREFIX = "refs/"
+LOCAL_PREFIX = REFERENCE_ROOT_PREFIX + "heads/"
+REMOTE_PREFIX = REFERENCE_ROOT_PREFIX + "remotes/"
+TAG_PREFIX = REFERENCE_ROOT_PREFIX + "tags/"
+# What rev-parse --symbolic-full-name answers for a detached HEAD; the grouped HEAD read of a commit ends with the same word.
+DETACHED_HEAD_NAME = "HEAD"
+# Number of characters of a commit id that the forms and the notices of the repository window show.
+SHORT_OID_LENGTH = 12
+# Separator of the folders in the paths Git writes and reads, whatever the system: Git always uses "/".
+GIT_PATH_SEPARATOR = "/"
+# Unicode category of control characters (C0, DEL and C1): never part of a path a user copied, and escaped when a path Git cited is shown.
+CONTROL_CHARACTER_CATEGORY = "Cc"
+# End of a line in what Git prints and in the text of the operation console.
+LINE_SEPARATOR = "\n"
+# Qt keeps the lines of a plain text document apart with this character in its raw text. The numbered editor turns it
+# into a line break, so a file that holds one stays read-only.
+QT_PARAGRAPH_SEPARATOR = "\u2029"
+WORKTREE_REFRESH_INTERVAL_MS = 5_000
+REBASE_REFRESH_INTERVAL_MS = 1_000
+REBASE_CAPTURE_ATTEMPTS = 3
+REBASE_FILE_LIMIT_BYTES = 256 * 1024
+REBASE_TOTAL_LIMIT_BYTES = 1024 * 1024
+REBASE_STEP_LIMIT = 5_000
+REBASE_CAPTURE_TIMEOUT_MS = GIT_READ_TIMEOUT_MS
+REBASE_CLOSE_REREAD_ATTEMPTS = 5
+# The folder of the common Git directory where the reftable format keeps references and their logs; the files format
+# has none, and keeps them as files under refs/ and logs/ instead.
+GIT_REFTABLE_DIR_BASENAME = "reftable"
+# The file Git keeps in a worktree's own Git directory while a merge waits for its commit: one commit ID per line, the
+# commits that become the parents after HEAD.
+MERGE_HEAD_BASENAME = "MERGE_HEAD"
+# The file next to it that tells how the merge was started; Git writes exactly this text into it when the merge must
+# keep every parent (git merge --no-ff), and otherwise drops from the commit any parent another parent already contains.
+MERGE_MODE_BASENAME = "MERGE_MODE"
+MERGE_MODE_NO_FAST_FORWARD = b"no-ff"
+# Largest MERGE_HEAD or MERGE_MSG read when a merge is concluded; a real one holds a few lines.
+MERGE_STATE_FILE_LIMIT_BYTES = 1024 * 1024
+REPLAY_FILE_LIMIT_BYTES = 1024 * 1024
+REPLAY_TOTAL_LIMIT_BYTES = 4 * REPLAY_FILE_LIMIT_BYTES
+REPLAY_INSTRUCTION_LIMIT = 10000
+REPLAY_CAPTURE_TIMEOUT_MS = 5000
+REPLAY_REFRESH_INTERVAL_MS = 2000
+# Bounds on reading the Cherry-pick and Revert journals earlier versions left: the size of one record and how many are read.
+REPLAY_RECORD_LIMIT_BYTES = 4 * 1024 * 1024
+REPLAY_RECORD_COUNT_LIMIT = 1000
+# How many files a refused Cherry-pick or Revert names when it would remove a submodule folder that still holds files
+# its own history does not record.
+SUBMODULE_LOSS_PATH_DISPLAY_LIMIT = 10
+WORKTREE_OUTPUT_LIMIT_BYTES = 32 * 1024 * 1024
+WORKTREE_INDEX_LIMIT_BYTES = 128 * 1024 * 1024
+WORKTREE_FILE_WORKER_COUNT = 2
+MUTATION_RECORD_LIMIT_BYTES = 64 * 1024
+IGNORE_RULE_LIMIT_BYTES = 8 * 1024 * 1024
+GIT_MUTATION_ENVIRONMENT_NAME_SET = frozenset({"GIT_INDEX_FILE"})
+GIT_ALTERNATE_OBJECT_ENVIRONMENT_NAME = "GIT_ALTERNATE_OBJECT_DIRECTORIES"
+GIT_INERT_EDITOR = ":"
+STAGING_WIDTH, STAGING_HEIGHT = 1200, 800
+STAGING_MIN_WIDTH, STAGING_MIN_HEIGHT = 800, 560
+FILE_HISTORY_ACTIVE_COMPARISON_LIMIT = 1
+FILE_HISTORY_BATCH_SIZE = 256
+FILE_HISTORY_CACHE_ENTRY_LIMIT = 1024
+FILE_HISTORY_COMPARISON_LIMIT = 10_000
+FILE_HISTORY_TURN_BUDGET_MS = 5
+# A Git-launched shell may describe its own repository; each read must discover the requested directory instead.
+GIT_LOCAL_ENVIRONMENT_NAMES = (
+    "GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+    "GIT_NAMESPACE", "GIT_PREFIX", "GIT_IMPLICIT_WORK_TREE", "GIT_GRAFT_FILE", "GIT_SHALLOW_FILE", "GIT_REPLACE_REF_BASE",
+    "GIT_CONFIG", "GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT", "GIT_CEILING_DIRECTORIES", "GIT_DISCOVERY_ACROSS_FILESYSTEM",
+)
+GIT_LOCAL_ENVIRONMENT_PREFIXES = ("GIT_CONFIG_KEY_", "GIT_CONFIG_VALUE_")
+# Command-scope setting given to every Git command GitPane starts, as a (key, value) pair. Under macOS and Windows, a
+# repository configured for fsmonitor makes Git start a background daemon that stays in the process group of the command
+# that started it, and a supervised command only ends once its whole group is gone. Passed through GIT_CONFIG_COUNT in the
+# environment rather than with -c, so no command line changes.
+GIT_FSMONITOR_SETTING = ("core.fsmonitor", "false")
+# Turns the millisecond time limits of this file into the seconds that Python's own waits take.
+MILLISECONDS_PER_SECOND = 1000
+# Turns a reading of the monotonic clock, in nanoseconds, into the milliseconds that timings are written in.
+NANOSECONDS_PER_MILLISECOND = 1_000_000
+# A shell reports a process ended by signal n with this base plus n, and so do GitPane's own exit codes.
+SIGNAL_EXIT_CODE_BASE = 128
+# Interpreter option that keeps the current folder (python -m) and the folder of a script started by its path (python
+# script.py) out of sys.path, so a gitpane folder in the folder a program starts from is never imported instead of the
+# installed GitPane.
+SAFE_PATH_OPTION = "-P"
+# Interpreter option that runs a module given by its dotted name.
+MODULE_OPTION = "-m"
+# Interpreter option that runs the Python text given as the next argument.
+CODE_OPTION = "-c"
+# Interpreter option of isolated mode: the user's Python environment variables, user site directory and current folder stay out of the child.
+ISOLATED_MODE_OPTION = "-I"
+# Interpreter option that loads no site directory at all, so only the standard library can be imported.
+NO_SITE_OPTION = "-S"
+# Interpreter options of a standard-library script GitPane starts: isolated mode, without any site directory.
+ISOLATED_INTERPRETER_OPTIONS = (ISOLATED_MODE_OPTION, NO_SITE_OPTION)
+# Interpreter option that ignores the PYTHON* variables the interpreter reads itself (PYTHONPATH, PYTHONHOME,
+# PYTHONSTARTUP, PYTHONNOUSERSITE...). The site module still reads PYTHONUSERBASE, which moves the user's site-packages
+# folder.
+IGNORE_ENVIRONMENT_OPTION = "-E"
+# Interpreter option that leaves the user's site-packages folder off the import path.
+NO_USER_SITE_OPTION = "-s"
+# Options of a GitPane module started as a program of its own (account worker, rebase editor bridge, SSH passphrase
+# prompt) by a GitPane that has the user's site-packages folder on its path. Unlike isolated mode, that folder stays on
+# the path: pip installs GitPane there when the Python's own folder is read-only.
+APPLICATION_MODULE_INTERPRETER_OPTIONS = (IGNORE_ENVIRONMENT_OPTION, SAFE_PATH_OPTION)
+
+
+def application_module_interpreter_options(no_user_site: bool) -> tuple[str, ...]:
+    """Answer the options of a GitPane module started as a program of its own, with the user's site-packages folder only when the GitPane that starts it has it.
+
+    ``no_user_site`` tells whether that GitPane runs without the folder: started with -s or -I, or with
+    PYTHONNOUSERSITE set (``sys.flags.no_user_site``). Under -E the program ignores PYTHONNOUSERSITE, so the folder is
+    left out by its own option; otherwise a gitpane installed there with pip --user could be imported by the program
+    while the GitPane that starts it runs another version, and both sides would no longer speak the same protocol.
+    """
+    if no_user_site:
+        return (*APPLICATION_MODULE_INTERPRETER_OPTIONS, NO_USER_SITE_OPTION)
+    return APPLICATION_MODULE_INTERPRETER_OPTIONS
+
+
+PROCESS_IDLE_TIMEOUT_MS = 10_000
+GIT_TRANSPORT_TIMEOUT_MS = 300_000
+GIT_CLONE_TIMEOUT_MS = 900_000
+AUTHENTICATION_TIMEOUT_MS = 600_000
+# Longest wait for the `git ls-remote` that tests a username + password account on its server before it is saved.
+ACCOUNT_CHECK_TIMEOUT_MS = 60_000
+# Longest wait for the `git ls-remote` that reads a remote repository's branches while a URL is typed in the clone form.
+GIT_BRANCH_LIST_TIMEOUT_MS = 60_000
+# How many times a Git network step is started again after Git Credential Manager could not read back a secret it keeps,
+# a failure that passes by itself: at most this many retries after the first attempt, so one more start in all.
+CREDENTIAL_READ_RETRY_LIMIT = 3
+# Wait between two starts of such a step, which gives the credential store time to answer again.
+CREDENTIAL_READ_RETRY_DELAY_MS = MILLISECONDS_PER_SECOND
+# How long a browser sign-in waits for the browser to answer, as chosen by the user: past it, the exchange with Git
+# Credential Manager is stopped and nothing is saved.
+BROWSER_SIGN_IN_TIMEOUT_MS = 120_000
+# Extra time the process supervisor gives a browser sign-in beyond that wait. The worker stops the browser wait itself;
+# this margin covers the identity check and the secure store that follow a late answer, and stops a worker that no
+# longer answers at all.
+BROWSER_SIGN_IN_STOP_GRACE_MS = 90_000
+# Longest time one check of the system credential store may take, for every account it covers together: it only asks
+# the credential helper whether each account's secret is still stored, never interactively and without any network
+# request, so a few seconds per account are plenty. Past it, the accounts not answered yet stay unknown.
+SECRET_LOOKUP_TIMEOUT_MS = 10_000
+# Extra time the process supervisor gives that check beyond its own limit, to start its worker and stop a late helper.
+SECRET_LOOKUP_STOP_GRACE_MS = 10_000
+# Longest time the erase of a secret an exchange left behind may take: it runs without any prompt, and nobody waits for
+# it. What it does not erase in time is erased by the next test of the same account or by the account's removal.
+SECRET_ERASE_TIMEOUT_MS = 10_000
+# Longest wait for the one request that recognises a server (GitHub or GitLab) after it refused a password; the same
+# default as the server detection of Git Credential Manager.
+SERVER_PROBE_TIMEOUT_MS = 2_000
+# Longest wait for the system to stop a process and every process it started, once its own time limit is over.
+PROCESS_TREE_STOP_TIMEOUT_MS = 5_000
+AUTHENTICATION_PREFERENCE_KEY = "authentication_selection"
+# How each connected account signs in, by account namespace. Kept apart from the account list so an older GitPane still
+# open at the same time, which does not know this key, keeps reading the account list.
+ACCOUNT_SIGN_IN_METHOD_PREFERENCE_KEY = "account_sign_in_method"
+# The answer kept for the question that links a pushed branch to its remote branch, by shared Git folder of the
+# repository. Kept apart from the account data, whose JSON refuses any key it does not know.
+PUSH_TRACKING_PREFERENCE_KEY = "push_tracking_by_repository"
+AUTHENTICATION_CONFIG_FILE_LIMIT = 128
+AUTHENTICATION_CONFIG_LIMIT_BYTES = 8 * 1024 * 1024
+GIT_DEFAULT_TEMPLATE_DIR = "%(prefix)/share/git-core/templates"
+SSH_PROMPT_TIMEOUT_MS = 120_000
+SSH_IPC_CONNECT_TIMEOUT_MS = 5_000
+SSH_PROMPT_LIMIT_BYTES = 16 * 1024
+SSH_RESPONSE_LIMIT_BYTES = 16 * 1024
+SSH_IPC_LIMIT_BYTES = 64 * 1024
+SSH_PENDING_CONNECTION_LIMIT = 4
+SSH_PROMPT_COUNT_LIMIT = 16
+SSH_NONCE_BYTES = 32
+SSH_ENVIRONMENT_NAMES = ("GITPANE_SSH_PIPE", "GITPANE_SSH_NONCE", "GITPANE_SSH_OPERATION", "GITPANE_SSH_OWNER_PID")
+TRANSPORT_IDLE_TIMEOUT_MS = 120_000
+AUTHENTICATION_IDLE_TIMEOUT_MS = 600_000
+TOOL_DOWNLOAD_TIMEOUT_SECONDS = 120
+# Longest wait for the mount command of macOS, which asks every mount point and so may wait on a dead network share;
+# past it, the recent folders are checked in a single group, as when no mount table can be read.
+MOUNT_TABLE_TIMEOUT_SECONDS = 2
+TOOL_BUILD_TIMEOUT_SECONDS = 600
+# Longest wait of a test or of a qualification tool for one step of its scenario, such as a window state, an
+# operation's result or one Git command it runs; the application itself never waits on it.
+SCENARIO_STEP_TIMEOUT_MS = 30_000
+QUALIFICATION_SCENARIO_TIMEOUT_SECONDS = 60
+# Bounds the single pytest child process the measuring tool starts for a reading. Not a test timeout. One hour was
+# sized for the process ceiling tests a reading used to run; since they were removed, a reading only collects the suite.
+PROCESS_MEASURE_TIMEOUT_SECONDS = 3_600
+TRACE_PAGE_SIZE = 200
+TRACE_UNIT_LIMIT_BYTES = 16 * 1024 * 1024
+TRACE_STORAGE_LIMIT_BYTES = 128 * 1024 * 1024
+TRACE_VIEW_LIMIT_BYTES = 64 * 1024
+TRACE_RENDER_INTERVAL_MS = 30
+# The byte counter under the console is a word-wrapped label: every rewrite asks the whole window to lay itself out
+# again, and twice a second is all the eye can follow while output streams in.
+TRACE_NAVIGATION_INTERVAL_MS = 500
+OPERATION_WIDTH, OPERATION_HEIGHT = 900, 560
+OPERATION_KEEP_OPEN_PREFERENCE_KEY = "operation_keep_open"
+
+
+class ConsoleOperation(Enum):
+    """Kind of work shown by the shared operation console; the kind alone decides whether the console offers Abort."""
+
+    FETCH = "fetch"
+    """Fetch and pull."""
+    PUSH = "push"
+    """Push, commit and push, and the tag push offered after creating a tag."""
+    REMOTE_DELETE = "remote-delete"
+    """Deletion of a remote branch or tag."""
+    CLONE = "clone"
+    """Clone, including the retry of its submodules."""
+    SUBMODULE_INIT = "submodule-init"
+    STASH_POP = "stash-pop"
+    REBASE = "rebase"
+    """Rebase start, todo edit, Continue and Abort."""
+    REFERENCE = "reference"
+    """Checkout, branch, tag, reset, cherry-pick and revert, including their Continue and Abort."""
+    HISTORY_REWRITE = "history-rewrite"
+    """Confirmed history publication whose stop waits for safe reconciliation."""
+
+
+# The end of every refusal of an outdated reference capture. The form that shows it blocks the repository window, so
+# the user closes it first; {refresh} and {shortcut} are filled from the real action and its shortcut on this system.
+STALE_CAPTURE_ADVICE = " Close this window, click {refresh} ({shortcut}), then try again."
+# The end of a refusal after which GitPane reads the repository again by itself, as a refused checkout does: clicking
+# Refresh would add nothing, the user only closes the form and tries again.
+REREAD_CAPTURE_ADVICE = " GitPane has read the repository again: close this window, then try again."
+
+
+class SharedText(Enum):
+    """Texts shown by several windows, or written by code outside the interface, one member per text so a misspelt name is an error."""
+
+    SETTING_BUTTON = "Settings…"
+    """The settings button of the welcome window."""
+    SETTING_BUTTON_MISSING_GIT = "Open settings"
+    """The same button while no usable Git has been found: it then only opens the settings to choose one."""
+    SETTING = "Settings"
+    """The settings action of the repository window and the title of the settings window."""
+    REFRESH = "Refresh"
+    """The action of the repository window that reads the repository again, which the refusals of an outdated reference capture name."""
+    RECENT_REPOSITORY = "Recent repositories"
+    HISTORY_REFRESH = "Refreshing…"
+    """The status bar text while the history is read again."""
+    TEXT_SEARCH_HELP = "Case-insensitive search; * matches characters within a word, including hyphens, but not whitespace. Other characters are literal."
+    """The tooltip of the find field of the commit message and of the diff."""
+    DETAIL_UNAVAILABLE = "Details unavailable"
+    """The start of the error a commit read gives when Git did not answer with its details."""
+    CHILD_LOADING = "Finding children…"
+    TERMINAL_CHOOSE = "Choose terminal"
+    RESULT_DETAILS = "Show details"
+    """The button next to a result in Prepare changes; the commit warning that tells the user to click it quotes it."""
+    COPY_DETAILS = "Copy details"
+    """The button that copies the shown details to the clipboard: the error window and the sign-in form read it here, while the operation console, the merge recovery window and the history rewrite windows still write the same text themselves."""
+    FAILED = "Failed"
+    """The status line of a console that failed, and a failed or refused step of Delete branch; the console lines written outside the interface use the same word."""
+    NOT_STARTED = "Not started"
+    """A step of Delete branch that never began; the console lines written outside the interface use the same word."""
+    OUTCOME_UNKNOWN = "Outcome unknown"
+    """An end GitPane could not observe: the status line of a console, and a step of Delete branch or Delete tag."""
+    REBASE_EDITOR_CLOSE_WAIT = "Waiting for the rebase editor: continue or abort the edit in GitPane."
+    """The start of the banner of a repository window that waits, before it closes or changes repository, for an edit Git asked for."""
+    REBASE_APPLYING_COMMITS = "Applying commits…"
+    """The progress line of a rebase while Git applies the commits: after the start, after an edit answered or lost, and after Continue rebase."""
+    SUBMODULE_CHECKOUT_REFUSED_START = "Submodule {submodule} could not be checked out: "
+    """The start of the sentence that explains a submodule whose checkout Git refused, in the console, the diagnostic and the clone form."""
+    CHECKOUT_REFUSED_WINDOWS_NAME = "Windows does not allow the file name '{path}'."
+    """Why Git refused a path under Windows; it also comes before the link reason when Windows refuses a part of the path. A path with ? is followed by CHECKOUT_REFUSED_QUESTION_MARK."""
+    CHECKOUT_REFUSED_OTHER_NAME = "Git did not accept the file name '{path}' on this system."
+    """Why Git refused a path under Linux or macOS, where the rule may be Git's own rather than the file system's."""
+    CHECKOUT_REFUSED_PROTECTED_PATH = "Git protects the path '{path}': it never writes a .git folder, or a name Windows reads as one, inside a repository."
+    """Why Git refused a path with a .git component, or one Windows reads as .git (git~1, .git with dots or spaces at the end), on every system: Git protects it, not the file system."""
+    CHECKOUT_REFUSED_PROTECTED_LINK = "Git protects the file name '{path}': it never writes it as a symbolic link."
+    """Why Git refused a path whose last part is, without case, exactly .gitmodules, .gitattributes, .gitignore or .mailmap, on every system: Git refuses these names only as a symbolic link."""
+    CHECKOUT_REFUSED_QUESTION_MARK = "Git shows a control character in a file name as ?."
+    """Added after the reason of a cited path that holds ?: Git writes ? for any control character, so the text never names one."""
+    SUBMODULE_CHECKOUT_REFUSED_END = "Other files of this submodule may have the same problem; Retry submodules cannot write them while these names exist in the repository. The rest of the clone is kept and can be opened."
+    """The end of that sentence: Git cites only the first name it refuses, and Retry submodules stays offered."""
+    CLONED_SUBMODULE_CHANGED = "The folder of submodule {submodule} changed after Git cloned it, so GitPane did not check it out. Existing files were preserved."
+    """Why GitPane stopped before checking out a submodule Git had cloned without its files: something appeared in its folder meanwhile."""
+    CLONED_SUBMODULE_CHECKOUT_NOT_STARTED = ("GitPane did not check out the submodules Git cloned without their files: the clone no longer holds its repository."
+                                             " Click Retry submodules to check them out.")
+    """Why the clone's step that checks out the submodules Git cloned without files did not run: the clone had already released its repository."""
+    CLONED_SUBMODULE_CHECKOUT_STEP = "Check out cloned submodules"
+    """The step of a clone that checks out the submodules Git cloned but left without files after refusing another submodule's checkout."""
+    UPSTREAM_LINK_STEP = "Set upstream branch"
+    """The step of a Push that links the pushed branch to its remote branch, shown in the console and in the details of the Push window."""
+    UPSTREAM_LINKED = "{branch} now tracks {tracking}."
+    """The console line once the pushed branch follows the remote-tracking branch it was pushed to."""
+    UPSTREAM_NOT_LINKED = "{branch} was pushed, but it was not linked to {tracking}: {cause}"
+    """The red console line when the link asked for after a successful Push was not set; the Push itself stays a success."""
+    UPSTREAM_NO_TRACKING_BRANCH = "no remote-tracking branch of {remote} receives {destination}"
+    """The cause of that line when no Fetch refspec of the remote maps the pushed destination to a remote-tracking branch."""
+    UPSTREAM_KEPT = "{branch} already has an upstream branch; it was left unchanged."
+    """The neutral console line when the pushed branch already has an upstream once the repository is read again after the Push: GitPane leaves that upstream as it is."""
+    UPSTREAM_OTHER_UPSTREAM = "Git reports {upstream} as its upstream branch"
+    """The cause of the not-linked line when Git accepted the link but resolves another upstream, as with several branch.<name>.remote values."""
+    UPSTREAM_NO_UPSTREAM = "Git reports no upstream branch"
+    """The cause of the not-linked line when Git accepted the link but the repository, read again, shows the branch without any upstream."""
+    UPSTREAM_UNREAD = "the upstream branch could not be read back: {cause}"
+    """The cause of the not-linked line when the repository could not be read again after the link, so the link is not known to be set."""
+    PUSH_TRACKING_UNREADABLE = "the " + PUSH_TRACKING_PREFERENCE_KEY + " entry of the preferences file is not a JSON object: remove it to go back to Ask for every repository"
+    """Why a kept tracking choice cannot be saved: the stored value of every repository's choices is not an object, so only removing it from gitpane.ini lets GitPane save again."""
+    SAVE_TRACKING_CHOICE = "Save tracking choice"
+    """The operation named in the diagnostic and the log when the answer kept by Don't ask again cannot be written to the preferences file."""
+    PUSH_TRACKING_NOT_SAVED = "Don't ask again was not saved: {cause}"
+    """The status bar line of the repository window when the tracking answer to keep cannot be written to the preferences file; the Push still goes with that answer."""
+    COMMIT_PUSH_CANCELLED = "Commit created. Push cancelled: the commit stays local."
+    """The status bar line of the repository window when the user answers Cancel to the tracking question of a Commit & push: the commit exists, nothing was sent."""
+    COMMIT_PUSH_NOT_SENT = "Commit created. Push not sent: this window may no longer push this repository. The commit stays local."
+    """The status bar line of the repository window when a Commit & push's created commit cannot be pushed because the window lost its authority to manage the repository: nothing was sent."""
+    CREDENTIAL_READ_RETRY = "The credential manager could not read the stored secret; trying again in {seconds} s ({attempt} of {limit})."
+    """The console and --log line of a Git network step started again because the credential manager could not read back a secret it keeps."""
+    CREDENTIAL_READ_RETRY_CANCELLED = "Cancelled while waiting to try again: Git was not started again."
+    """The cause of an operation cancelled, or of GitPane closing, while a network step waited to be started again."""
+    REFERENCE_CHANGED_BEFORE_OPENING = "The repository changed since GitPane last read it (branches, tags or Git settings)." + STALE_CAPTURE_ADVICE
+    """A reference form refused when it opens: the references or the Git settings differ from the capture its menu was built on."""
+    SELECTED_REFERENCE_OR_REPOSITORY_CHANGED = ("The repository changed since GitPane last read it (the selected branch or tag, other branches or tags, or Git settings)."
+                                                + STALE_CAPTURE_ADVICE)
+    """Delete branch or Delete tag refused when it opens: the clicked branch or tag, or the rest of the capture its menu was built on, changed."""
+    SELECTED_LOCAL_BRANCH_CHANGED = "The selected local branch changed or was deleted since GitPane last read it." + STALE_CAPTURE_ADVICE
+    """A branch form refused because the local branch it acts on moved, disappeared or is no longer a plain local branch."""
+    HEAD_CHANGED_BEFORE_OPENING = "The current branch or commit changed since GitPane last read the repository." + STALE_CAPTURE_ADVICE
+    """Checkout branch or Checkout revision refused when it opens: HEAD differs from the capture its menu was built on."""
+    SELECTED_REFERENCE_CHANGED = "The selected branch or tag changed or was deleted since GitPane last read it." + STALE_CAPTURE_ADVICE
+    """A checkout or a deletion refused because the branch or tag it acts on no longer points where the capture said, or is gone."""
+    FORM_CHECK_UNANSWERED = "GitPane got no answer while checking the repository for this form; try again."
+    """A reference form closed before it was ever shown because its opening check gave no answer within its limit; the next click opens a new form."""
+    NOT_A_LOCAL_BRANCH = "GitPane does not know '{branch}' as a local branch: the branches may have changed since it last read the repository." + STALE_CAPTURE_ADVICE
+    """A deletion of local branches refused before any process: a requested name is not a plain local branch of the capture."""
+    REFERENCE_CHANGED_DURING_READING = ("The branches, tags or current commit changed while GitPane was reading them."
+                                        " Close any open form, click {refresh} ({shortcut}), then try again.")
+    """A reference read that saw the files change while it ran, shown in the status bar of the repository window or in a form."""
+    SELECTED_REFERENCE_CHANGED_OR_SYMBOLIC = ("The selected branch or tag changed since GitPane last read it, or it is now another name for a branch (a symbolic reference)."
+                                              + REREAD_CAPTURE_ADVICE)
+    """A checkout refused when it starts: the chosen branch or tag moved, disappeared or became a symbolic reference."""
+    CHECKOUT_REFERENCES_OR_HEAD_CHANGED = "The branches, tags or current commit changed since GitPane last read the repository." + REREAD_CAPTURE_ADVICE
+    """A checkout refused when it starts: the references or the current commit are no longer those the form was opened on."""
+    CHECKOUT_LOCAL_BRANCH_GONE = "The local branch to reset no longer exists." + REREAD_CAPTURE_ADVICE
+    """A checkout that resets a local branch onto its remote branch, refused when it starts because that local branch was deleted."""
+    CHECKOUT_CHANGED_BEFORE_LAUNCH = ("The repository changed just before Git started the checkout (branches, tags, current commit or Git settings)."
+                                      + REREAD_CAPTURE_ADVICE)
+    """A checkout refused at the last moment: the references or Git settings changed, or the request stopped being current, while it waited to start."""
+
+
+# Only a network transfer can be stopped midway from the console: it waits on a server and stopping it leaves the
+# repository as it was. Every other console runs a local write that must finish, so it hides the Abort button, and
+# Escape or the close button do not stop it either. A paused rebase, cherry-pick or revert is abandoned from the
+# repository window instead.
+CONSOLE_ABORTABLE_OPERATION_SET = frozenset((ConsoleOperation.FETCH, ConsoleOperation.PUSH, ConsoleOperation.REMOTE_DELETE, ConsoleOperation.CLONE, ConsoleOperation.SUBMODULE_INIT, ConsoleOperation.HISTORY_REWRITE))
+DIAGNOSTIC_DECODE_LIMIT = 8
+# The OAuth authorization code field. The same word also names exit, HTTP and Git error codes, so the secret filter lets
+# a short number after it through; every other value stays hidden.
+AUTHORIZATION_CODE_FIELD_NAME = "code"
+SENSITIVE_FIELD_NAMES = (
+    "authorization", "proxy-authorization", "cookie", "set-cookie", "password", "passwd", "access_token", "refresh_token", "id_token", "token", AUTHORIZATION_CODE_FIELD_NAME,
+    "code_verifier", "verifier", "state", "nonce", "client_secret", "secret", "api_key", "apikey", "credential",
+)
+# A value shorter than this is never hidden in diagnostics and logs: hiding a one-character value, such as the "0" of
+# a trace switch, rewrites every line it appears in (times, object names, counts) and protects nothing.
+SENSITIVE_VALUE_MIN_LENGTH = 2
+# The environment variable through which Git Credential Manager reads each of its settings that GitPane depends on, named
+# as in Git configuration. Git Credential Manager reads such a variable before any Git configuration, even before a
+# setting the user scoped to one address, and it only matches a URL-scoped setting against the host Git sends it, never
+# against a repository path; a helper started with these variables therefore finds its account whatever URL Git chose
+# that helper for, whatever the user's own configuration says. Every other setting of Git Credential Manager (its proxy,
+# its prompts window…) stays the user's.
+GCM_ENVIRONMENT_NAME_BY_SETTING = {"provider": "GCM_PROVIDER", "namespace": "GCM_NAMESPACE", "credentialStore": "GCM_CREDENTIAL_STORE",
+                                   "interactive": "GCM_INTERACTIVE", "traceSecrets": "GCM_TRACE_SECRETS", "allowWindowsAuth": "GCM_ALLOW_WINDOWSAUTH",
+                                   "gitHubAuthModes": "GCM_GITHUB_AUTHMODES", "gitLabAuthModes": "GCM_GITLAB_AUTHMODES", "bitbucketAuthModes": "GCM_BITBUCKET_AUTHMODES"}
+GCM_TRACE_SECRETS_NAME = GCM_ENVIRONMENT_NAME_BY_SETTING["traceSecrets"]
+# Environment names that look secret but hold no secret: the Git Credential Manager switch that keeps secrets out of
+# its own trace has "SECRET" in its name, yet its value is only "0" or "1".
+NON_SECRET_ENVIRONMENT_NAME_SET = frozenset({GCM_TRACE_SECRETS_NAME})
+NETWORK_ENVIRONMENT_VALUE_SET_BY_NAME = {
+    "GIT_TRACE": frozenset({"1"}), "GIT_TRACE_CURL": frozenset({"1"}), "GIT_TRACE_CURL_NO_DATA": frozenset({"0", "1"}),
+    "GIT_TRACE_REDACT": frozenset({"1"}), "GCM_TRACE": frozenset({"1"}), GCM_TRACE_SECRETS_NAME: frozenset({"0"}),
+    "GIT_CONFIG_NOSYSTEM": frozenset({"1"}), "NO_PROXY": frozenset({"*"}),
+}
+PROCESS_TERMINATE_TIMEOUT_MS = 500
+PROCESS_GROUP_POLL_MS = 25
+COMMIT_BATCH_SIZE = 200
+SEARCH_DEBOUNCE_MS = 250
+# Typing pause after which a revision typed in a revision field is resolved: nothing is resolved while the user is
+# still typing, so a revision that needs Git costs one process after the pause instead of one per key.
+REVISION_INPUT_PAUSE_MS = 400
+RELATIVE_DATE_REFRESH_MS = 60_000
+AVATAR_SIDE = 64
+AVATAR_INITIALS_FILL_RATIO = 0.85
+AVATAR_TIMEOUT_MS = 5_000
+AVATAR_ACTIVE_LIMIT = 4
+AVATAR_PENDING_LIMIT = 128
+AVATAR_RESPONSE_LIMIT_BYTES = 2 * 1024 * 1024
+AVATAR_DECODED_SIDE_LIMIT = 1024
+AVATAR_REQUEST_SIDE_LIMIT = 512
+AVATAR_CACHE_ENTRY_LIMIT = 128
+AVATAR_CACHE_LIMIT_BYTES = 16 * 1024 * 1024
+AVATAR_CACHE_TTL_SECONDS = 3600
+TOOL_START_TIMEOUT_MS = 5_000
+MERGETOOL_START_TIMEOUT_MS = TOOL_START_TIMEOUT_MS
+MERGETOOL_TERMINATE_TIMEOUT_MS = PROCESS_TERMINATE_TIMEOUT_MS
+WINDOWS_EXCEPTION_STATUS_START = 0x80000000
+SHELL_SCRIPT_EXTENSION_SET = frozenset({".bat", ".cmd"})
+TOOL_START_ACTIVE_LIMIT = 4
+DIFFTOOL_START_TIMEOUT_MS = 5_000
+DIFFTOOL_ACTIVE_LIMIT = 4
+TOOL_RESULT_POLL_MS = 25
+FILE_EXPORT_BUFFER_CHUNKS = 128
+FILE_EXPORT_ACTIVE_LIMIT = 2
+COPY_CONFIRMATION_MS = 3_000
+PARSING_BUDGET_MS = 5
+STDERR_LIMIT_BYTES = 256 * 1024
+COMMIT_LIMIT_BYTES = 8 * 1024 * 1024
+MESSAGE_CACHE_LIMIT_BYTES = 32 * 1024 * 1024
+DIFF_CACHE_LIMIT_BYTES = 16 * 1024 * 1024
+DIFF_CACHE_ENTRY_LIMIT = 128
+# Keep text layout small even for generated files; stream exact bytes separately for export.
+FILE_PREVIEW_LIMIT_BYTES = 256 * 1024
+FILE_LINE_LIMIT_CHARS = 4096
+FILE_PARSE_BUDGET_MS = 5
+FILE_CACHE_LIMIT_BYTES = 8 * 1024 * 1024
+FILE_TEXT_BATCH_CHARS = 8192
+SESSION_PROCESS_LIMIT = 2
+GLOBAL_PROCESS_LIMIT = 4
+
+
+class ProcessPriority(IntEnum):
+    """Order in which waiting Git processes take a free slot; a smaller value goes first.
+
+    A user action goes before the rest of an operation already under way, and both go before background work such as
+    the periodic refresh. The level only orders the waiting queue: it grants no permission, never changes a launch
+    profile and never interrupts a process that already runs.
+    """
+
+    USER = 0
+    CONTINUATION = 1
+    BACKGROUND = 2
+
+
+SESSION_QUEUE_LIMIT = 64
+GLOBAL_QUEUE_LIMIT = 256
+PROCESS_CHUNK_BYTES = 64 * 1024
+# The one byte asked beyond a validated file size, so that a file which grew while it was read shows it.
+READ_SIZE_SENTINEL_BYTES = 1
+PARSING_BACKLOG_LIMIT_BYTES = 8 * 1024 * 1024
+SNAPSHOT_RETRY_LIMIT = 3
+CAT_FILE_HEADER_LIMIT_BYTES = 256
+COMMIT_HEADER_LIMIT_BYTES = 64 * 1024
+HISTORY_REWRITE_SPOOL_LIMIT_BYTES = 4 * 1024 * 1024 * 1024
+HISTORY_REWRITE_DIAGNOSTIC_LIMIT_CHARS = 2048
+COMMIT_SUBJECT_LIMIT_CHARS = 512
+COMMIT_PREVIEW_LIMIT_CHARS = 512
+# Repositories the recent history keeps, the most recent first. The Open repository window and the repository switch
+# menu show as many, and scroll past what fits.
+RECENT_LIMIT = 100
+# How long a recent's folder check may go without an answer before its row shows "checking": a folder on a local disk
+# answers within a few milliseconds and so never shows it, and the recent list does not jump when the window opens.
+RECENT_CHECKING_DISPLAY_DELAY_MS = 300
+# How long after its check was requested a recent without an answer is shown as Unknown, even one still waiting behind a slow disk.
+# A question blocked on a dead network mount cannot be cancelled, so the window stops waiting for it; its answer is still taken if it ever comes.
+RECENT_CHECK_UNKNOWN_DELAY_MS = 30_000
+# Parent folders of the last started clones offered by the clone form's Destination list.
+CLONE_DESTINATION_LIMIT = 10
+FIRST_ROW = 0
+# Qt measures arc angles in sixteenths of a degree, starting at three o'clock.
+QT_ANGLE_UNITS_PER_DEGREE = 16
+# Shown in place of the commit subject by the branch forms when the selected commit could not be read.
+COMMIT_METADATA_UNAVAILABLE = "Commit metadata unavailable"
+# Text of the submit button of the forms that delete a branch or a tag.
+DELETE_BUTTON_TEXT = "Delete"
+# Title of both Delete branch windows and of the questions they ask.
+DELETE_BRANCH_TITLE = "Delete branch"
+# Text of the button that confirms a form whose action has no more precise name.
+OK_BUTTON_TEXT = "OK"
+# Shortcuts shared by the action that reacts to them and by the tooltip that cites them, in Qt's portable format.
+FIND_SHORTCUT = "Ctrl+F"
+STAGE_SHORTCUT = "S"
+WELCOME_WIDTH = 720
+REPOSITORY_WIDTH = 1440
+REPOSITORY_HEIGHT = 900
+LAYOUT_SPACING = 8
+APPLICATION_NAME = "GitPane"
+# The build reads this value from the text of this file without running it, so it stays a literal written as is:
+# a computed value would make the build import the module instead.
+APPLICATION_VERSION = "1.0.0"
+# The line `gitpane --version` prints and the diagnostic log writes first.
+APPLICATION_VERSION_LINE = APPLICATION_NAME + " " + APPLICATION_VERSION
+# Bounds the helper that marks or writes the desktop shortcut (gio on Linux, PowerShell on Windows); it runs off the
+# window's thread, so a slow helper never freezes Settings.
+DESKTOP_SHORTCUT_HELPER_TIMEOUT_MS = 30_000
+# Windows groups taskbar buttons by this identifier. Company.Product format, without a version so an update keeps the same button.
+APPLICATION_USER_MODEL_ID = "ThongvanAlexis.GitPane"
+# macOS knows the desktop bundle of GitPane by this reverse-DNS name. The Windows identifier above is not reused: it is not in that form.
+MACOS_BUNDLE_IDENTIFIER = "io.github.thongvanalexis.gitpane"
+WINDOWS_PLATFORM = "win32"
+LINUX_PLATFORM = "linux"
+MACOS_PLATFORM = "darwin"
+# Linux's process folder, read by the process supervisor (process states) and by the keyring read (the program a process runs).
+PROC_DIR = "/proc"
+# The Windows environment variable that names the Windows folder, read by the terminal search and the SSH client search.
+SYSTEM_ROOT_ENVIRONMENT_NAME = "SystemRoot"
+# The Unicode form macOS gives the names it creates and Qt for macOS gives every argument: accents decomposed into a letter and a combining mark.
+DECOMPOSED_UNICODE_FORM = "NFD"
+# The macOS command that hands a file, a folder or an application to LaunchServices (Finder, Terminal, default editor).
+MACOS_OPEN_FILENAME = "/usr/bin/open"
+# Start of every HTTPS URL and account origin; shared by the account service and the reader of Git's refusal lines.
+HTTPS_PREFIX = "https://"
+WINDOWS_KDIFF3_FILENAME = "C:/Program Files/KDiff3/kdiff3.exe"
+# Where the distribution packages install KDiff3.
+LINUX_KDIFF3_FILENAME = "/usr/bin/kdiff3"
+# Standard KDiff3 installation of each system, keyed by sys.platform, offered in Settings when no comparison tool is saved.
+# macOS has no fixed file: its KDiff3 is an application bundle, searched through KDIFF3_BUNDLE_BASENAMES_BY_PLATFORM below.
+# A system missing from the table gets no suggestion rather than another system's location.
+KDIFF3_SUGGESTED_FILENAMES_BY_PLATFORM: dict[str, tuple[str, ...]] = {
+    WINDOWS_PLATFORM: (WINDOWS_KDIFF3_FILENAME,),
+    LINUX_PLATFORM: (LINUX_KDIFF3_FILENAME,),
+    MACOS_PLATFORM: (),
+}
+# Homebrew's kdiff3 cask and KDE's disk image both install this application folder.
+KDIFF3_BUNDLE_BASENAME = "kdiff3.app"
+# KDiff3 application folders of each system, keyed by sys.platform, searched in the applications folders after the fixed
+# files above. GitPane offers the program the bundle declares, the same one Browse… gives on that folder, never the script
+# the cask adds to Homebrew's bin folder. A system missing from the table gets no suggestion.
+KDIFF3_BUNDLE_BASENAMES_BY_PLATFORM: dict[str, tuple[str, ...]] = {
+    WINDOWS_PLATFORM: (),
+    LINUX_PLATFORM: (),
+    MACOS_PLATFORM: (KDIFF3_BUNDLE_BASENAME,),
+}
+# KDE's download folder of the stable KDiff3 releases, which holds the Windows installer (.exe).
+KDIFF3_DOWNLOAD_URL = "https://download.kde.org/stable/kdiff3/"
+# How to install KDiff3 on Windows and macOS, keyed by sys.platform: shown under the tool fields of Settings while no
+# KDiff3 is found, and after the message of a comparison or a conflict resolution refused for a missing tool. Linux has
+# one line per distribution, in gitpane/tool/kdiff3_install.py. Any other system gets no line rather than another
+# system's.
+KDIFF3_INSTALL_LINE_BY_PLATFORM: dict[str, str] = {
+    WINDOWS_PLATFORM: "To install KDiff3, download its Windows installer from " + KDIFF3_DOWNLOAD_URL,
+    MACOS_PLATFORM: "To install KDiff3, run: brew install --cask kdiff3",
+}
+# Oldest Git Credential Manager that accepts every setting GitPane passes to it (the "none" store included) and that
+# carries the fix for CVE-2024-50338; an older one is refused with its version so the user knows what to update.
+GCM_MINIMUM_VERSION = (2, 6, 1)
+# Longest wait for `git-credential-manager --version`: the first start of .NET on Windows, antivirus scan included, can
+# take several seconds.
+GCM_VERSION_TIMEOUT_MS = 10_000
+# Start of the names of the environment variables the Git Credential Manager reads as its own settings. Every place
+# that drops the user's settings before starting it, or before starting Git that starts it, reads this one value.
+GCM_ENVIRONMENT_PREFIX = "GCM_"
+GCM_RELEASES_URL = "https://github.com/git-ecosystem/git-credential-manager/releases/latest"
+# Version of the official .tar.gz archive the Linux install lines download: the latest stable release when these lines
+# were written, at least GCM_MINIMUM_VERSION. Raised by hand when a newer release is worth giving.
+GCM_ARCHIVE_VERSION = "3.0.2"
+GIT_FOR_WINDOWS_DOWNLOAD_URL = "https://git-scm.com/downloads/win"
+# Where a Mac without Homebrew gets it before installing the credential manager with it.
+HOMEBREW_INSTALL_URL = "https://brew.sh"
+# First line of the "credential manager missing" message, the same on every system; the install lines of the table follow it.
+GCM_REQUIRED_TEXT = "A git credential manager is required to push/fetch"
+GCM_WINDOWS_BASENAME = "git-credential-manager.exe"
+GCM_BASENAME = "git-credential-manager"
+# Where the .pkg installer of the Homebrew cask, the official .deb and the archive install lines all put the credential
+# manager, on Apple silicon and Intel alike. An application started from the Finder or from the desktop menu does not
+# always have /usr/local/bin in its PATH, and the archive lines put no link there, so this location is searched after
+# the PATH. posixpath, because the path is POSIX on both systems that use it, whatever system runs the tests.
+GCM_CORE_DIR = "/usr/local/share/gcm-core"
+GCM_CORE_FILENAME = posixpath.join(GCM_CORE_DIR, GCM_BASENAME)
+# Install line of the macOS entry, given both for a missing credential manager and for one that is installed but unusable.
+MACOS_GCM_INSTALL_LINE = " - run : brew install --cask git-credential-manager"
+
+
+@dataclass(frozen=True)
+class CredentialManagerPlatform:
+    """Everything about the Git Credential Manager that differs from one system to another.
+
+    Its file name, whether the Git installation in use is searched for it, the fixed locations searched after the
+    PATH, the secure store that keeps GitPane's accounts, and the install lines shown when it is refused, which may
+    depend on why it is refused.
+    """
+
+    executable_basename: str
+    searches_git_installation: bool
+    fixed_filenames: tuple[str, ...]
+    credential_store: str
+    # Lines for a credential manager that is installed but unusable (unreadable version, does not start), and for any
+    # refusal that has no lines of its own below.
+    install_lines: tuple[str, ...]
+    # A missing credential manager and one that is too old are not installed the same way everywhere (install versus
+    # upgrade); empty means the same lines as install_lines.
+    missing_install_lines: tuple[str, ...] = ()
+    too_old_install_lines: tuple[str, ...] = ()
+    # True when the lines depend on the distribution and the processor, written by the module of the Linux install
+    # lines; install_lines then stays empty.
+    install_lines_by_distribution: bool = False
+
+
+# Keyed by sys.platform. A system missing from the table is refused as unsupported, never served with another system's
+# location, store or install lines.
+CREDENTIAL_MANAGER_PLATFORM_BY_NAME: dict[str, CredentialManagerPlatform] = {
+    WINDOWS_PLATFORM: CredentialManagerPlatform(
+        executable_basename=GCM_WINDOWS_BASENAME, searches_git_installation=True, fixed_filenames=(), credential_store="wincredman",
+        install_lines=(' - reinstall Git for Windows with "Git Credential Manager" checked', " - You can get it there in case you forgot : " + GIT_FOR_WINDOWS_DOWNLOAD_URL),
+    ),
+    LINUX_PLATFORM: CredentialManagerPlatform(
+        executable_basename=GCM_BASENAME, searches_git_installation=False, fixed_filenames=(GCM_CORE_FILENAME,), credential_store="secretservice",
+        install_lines=(), install_lines_by_distribution=True,
+    ),
+    MACOS_PLATFORM: CredentialManagerPlatform(
+        executable_basename=GCM_BASENAME, searches_git_installation=False, fixed_filenames=(GCM_CORE_FILENAME,), credential_store="keychain",
+        install_lines=(MACOS_GCM_INSTALL_LINE,),
+        missing_install_lines=(MACOS_GCM_INSTALL_LINE, " - no Homebrew yet? install it first : " + HOMEBREW_INSTALL_URL),
+        too_old_install_lines=(" - run : brew upgrade --cask git-credential-manager",),
+    ),
+}
+SPACING_XS, SPACING_SM, SPACING_MD, SPACING_LG, SPACING_XL, SPACING_2XL, SPACING_3XL = 4, 8, 16, 24, 32, 48, 64
+SCREEN_MARGIN = SPACING_MD
+# Rows the repository switch list shows at once, like an ordinary dropdown list; it scrolls past them.
+REPOSITORY_LIST_MAX_VISIBLE_ROW_COUNT = 20
+# Gap added after the number and after the name in the repository switch list; Qt already counts a small style margin in
+# each measured column.
+REPOSITORY_LIST_COLUMN_GAP = SPACING_SM
+# The Open repository buttons sit in the band under the form, so the form itself is short: the minimum height stays
+# under the height the form wants with a few recent repositories, so the window still grows with them.
+WELCOME_MIN_WIDTH, WELCOME_MIN_HEIGHT = 480, 240
+# The Open repository form grows with its recent repositories up to this share of the usable screen height; past it, the form scrolls.
+WELCOME_MAX_SCREEN_RATIO = 0.8
+REPOSITORY_MIN_WIDTH, REPOSITORY_MIN_HEIGHT = 800, 560
+SETTING_WIDTH, SETTING_HEIGHT = 800, 600
+SETTING_MIN_WIDTH, SETTING_MIN_HEIGHT = 480, 320
+ERROR_WIDTH, ERROR_HEIGHT = 640, 320
+# Share of the usable screen height the diagnostic window never goes past, title bar included; past it, its details scroll.
+ERROR_MAX_SCREEN_HEIGHT_RATIO = 0.8
+# Share of the room left to the cause and the details that the cause may take when the diagnostic window is at its height cap.
+ERROR_SUMMARY_MAX_SHARE = 0.5
+# Client-area width of the Git Extensions Cherry pick commit and Revert commit windows (615 px with their borders); the
+# height follows the content. The revision chooser keeps the same starting size.
+REPLAY_DIALOG_WIDTH = 613
+REPLAY_DIALOG_HEIGHT = 360
+NAVIGATION_WIDTH, NAVIGATION_MIN_WIDTH = 240, 160
+HISTORY_MIN_HEIGHT, DETAIL_MIN_HEIGHT = 192, 200
+HISTORY_STRETCH, DETAIL_STRETCH = 1, 1
+HISTORY_ROW_MIN_HEIGHT = 24
+# The package and the folder where GitPane keeps the images and the font it ships, read through importlib.resources.
+# Every reader takes them from here, so moving the resources means changing one place.
+UI_RESOURCE_PACKAGE_NAME = "gitpane.ui"
+UI_RESOURCE_DIR_NAME = "resource"
+# Names of the packaged application pictures that the icon drawing tool writes into that folder, read by the desktop shortcut.
+APPLICATION_ICON_FILE_NAME_PREFIX = "GitPane-"
+APPLICATION_ICON_PNG_EXTENSION = ".png"
+APPLICATION_ICON_ICO_BASENAME = "GitPane.ico"
+ICON_SIDE, GRAPH_NODE_SIDE, GRAPH_LANE_WIDTH = 16, 8, 16
+PARENT_MARKER_FILL = "#e87500"
+PARENT_MARKER_BORDER = "#c73939"
+PARENT_MARKER_BACKGROUND = "#ffffff"
+PARENT_MARKER_BORDER_WIDTH = 1
+PARENT_MARKER_INSET = 2
+PARENT_MARKER_SHOULDER_RATIO = 0.55
+PARENT_MARKER_SHAFT_RATIO = 0.3
+GRAPH_MESSAGE_MIN_CHARACTERS = 12
+TERMINAL_CONTROL_HEIGHT = 32
+# Arrow of the toolbar menu buttons, measured at 100 % on a Git Extensions toolbar capture: a filled triangle whose
+# rows are 7, 5, 3 and 1 pixels wide, 9 pixels after the end of the button text.
+MENU_ARROW_WIDTH, MENU_ARROW_HEIGHT = 7, 4
+MENU_ARROW_TEXT_GAP = 9
+MENU_ARROW_AREA_WIDTH = 11
+MENU_SEPARATOR_WIDTH = 1
+# Right padding of the button content, tuned so the measured gap equals MENU_ARROW_TEXT_GAP with the fonts of Windows and
+# Linux: Qt adds two spaces of the button font after the text and the triangle is centred in the menu area, so the gap is
+# larger than this padding and grows with the font's space. The pixel test checks the gap this layout gives in the button's
+# font on every system, and that it equals MENU_ARROW_TEXT_GAP on Windows and Linux (macOS buttons get a smaller font).
+MENU_ARROW_TEXT_PADDING = 2
+# Top bar of the repository window: the repository button gives way to the filter and commit hash fields, which
+# keep at least these widths. The button shows the whole path up to its maximum width and elides it in the middle below
+# that, down to its minimum text width. Starting values, to be judged on screen captures at 100 %.
+REPOSITORY_BUTTON_MAX_WIDTH = 480
+REPOSITORY_BUTTON_MIN_TEXT_WIDTH = 64
+# Narrower than the hash field since the filter mode button, wider than the label it replaced, sits beside it: at the
+# minimum window width the repository button still shows the repository name with its separator.
+FILTER_FIELD_MIN_WIDTH = 104
+HASH_FIELD_MIN_WIDTH = 120
+TOP_BAR_FIELD_STRETCH = 1
+HEADING_FONT_RATIO, DISPLAY_FONT_RATIO = 1.25, 1.75
+MESSAGE_LINE_HEIGHT_PERCENT = 150
+DIFF_FRAGMENT_LIMIT_CHARS = 4096
+DIFF_SYNTAX_LIMIT_CHARS = 16384
+DIFF_ICON_PADDING_RATIO = 0.2
+DIFF_ICON_STROKE_RATIO = 0.14
+DIFF_ICON_RENAME_BADGE_AREA_RATIO = 0.25
+DIFF_NUMBER_COLUMN_COUNT = 2
+DIFF_FILE_STRETCH, DIFF_TEXT_STRETCH = 1, 3
+# The message splitter has a third pane for the emoji keyboard, but its preference keeps two sizes: upper (diff and keyboard) and message.
+STAGING_MESSAGE_PROPORTION_KEY = "staging_message_proportions"
+STAGING_PROPORTION_BY_KEY: dict[str, tuple[int, int]] = {
+    "staging_file_proportions": (DIFF_FILE_STRETCH, DIFF_TEXT_STRETCH),
+    "staging_list_proportions": (1, 1),
+    STAGING_MESSAGE_PROPORTION_KEY: (DIFF_TEXT_STRETCH, DIFF_FILE_STRETCH),
+}
+# Duration of the slide that opens or closes the staging emoji keyboard.
+EMOJI_GRID_ANIMATION_MS = 150
+# Colour emoji glyphs ignore the palette's disabled colour, so a disabled keyboard is dimmed to this opacity to look disabled.
+EMOJI_GRID_DISABLED_OPACITY = 0.4
+EMOJI_POINT_SIZE = 18
+EMOJI_BUTTON_MIN_SIDE = SPACING_XL
+# Combining mark buttons show the mark between two emoji, so they are this many symbol buttons wide.
+EMOJI_MARK_BUTTON_WIDTH_RATIO = 2
+# Shared label of the staging button, the Tools menu action and the title of the floating keyboard window.
+EMOJI_KEYBOARD_TITLE = "Emoji keyboard"
+# How long the floating keyboard's copy bubble stays up; copied hashes keep their own, longer status confirmation.
+EMOJI_COPY_TOAST_MS = 1_200
+COPIED_TO_CLIPBOARD_TEXT = "Copied to clipboard"
+# The floating keyboard first opens at this share of the usable screen width, then as tall as its laid-out grid needs to
+# show every symbol at that width; it only grows wider when that height does not fit on the screen.
+EMOJI_WINDOW_SCREEN_WIDTH_SHARE = 0.4
+EMOJI_WINDOW_MIN_WIDTH, EMOJI_WINDOW_MIN_HEIGHT = 240, 160
+EMOJI_WINDOW_GEOMETRY_PREFERENCE_KEY = "emoji_window_geometry"
+
+
+SUBMODULE_SUMMARY_OUTPUT_LIMIT_BYTES = 1024 * 1024
+SUBMODULE_SUMMARY_COMMIT_LIMIT = 100
+SUBMODULE_SUMMARY_DIFFERENCE_LIMIT = 500
+
+
+def round_up_to_spacing(value: int) -> int:
+    """Round a size up to the next multiple of the smallest spacing, so that controls stay on the spacing grid."""
+    return ((value + SPACING_XS - 1) // SPACING_XS) * SPACING_XS
+
+
+def application_icon_png_basename(side: int) -> str:
+    """Return the name of the packaged PNG picture of the application logo drawn ``side`` pixels wide."""
+    return APPLICATION_ICON_FILE_NAME_PREFIX + str(side) + APPLICATION_ICON_PNG_EXTENSION
+
+
+def control_height(font_height: int) -> int:
+    """Round a readable control height upward without scaling logical pixels twice."""
+    return round_up_to_spacing(max(SPACING_XL, font_height + SPACING_SM))
+
+
+def emoji_button_side(font_height: int) -> int:
+    """Return the side of a square emoji button: the symbol plus a small margin, never below the minimum, on the spacing grid."""
+    return round_up_to_spacing(max(EMOJI_BUTTON_MIN_SIDE, font_height + SPACING_XS))
+
+
+def history_row_height(font_height: int) -> int:
+    """Keep the history compact while giving enlarged system fonts room to breathe."""
+    return max(HISTORY_ROW_MIN_HEIGHT, font_height + SPACING_SM)
+
+
+def keep_selection_visible(widget: QWidget) -> bool:
+    """Retain the system highlight while another control in the window owns focus; answer whether the palette had to change.
+
+    Starts from the widget's own palette, which pins only the colors set here: a copy of the application palette would
+    also pin the window and field colors GitPane lays in a light theme, and the widget would keep them after a switch
+    to a dark theme. A palette that already has them is left alone, so no palette change is raised for nothing.
+    """
+    from PySide6.QtGui import QPalette
+
+    palette = widget.palette()
+    changed = False
+    for role in (QPalette.ColorRole.Highlight, QPalette.ColorRole.HighlightedText):
+        active_color = palette.color(QPalette.ColorGroup.Active, role)
+        if palette.color(QPalette.ColorGroup.Inactive, role) == active_color and palette.isBrushSet(QPalette.ColorGroup.Inactive, role):
+            continue
+        palette.setColor(QPalette.ColorGroup.Inactive, role, active_color)
+        changed = True
+    if changed:
+        widget.setPalette(palette)
+    return changed
+
+
+def fit_window(widget: QWidget, minimum_width: int, minimum_height: int, available: QRect | None = None, *, platform_name: str = "") -> None:
+    """Keep the frame inside usable screen space, relaxing nominal minima on small screens.
+
+    The size is fitted on every platform. Where the compositor places windows itself, the frame is not moved back
+    inside the area: the compositor ignores the position. ``platform_name`` is Qt's platform name, read from Qt when not
+    given.
+    """
+    from PySide6.QtCore import QPoint
+
+    available = (available if available is not None else widget.screen().availableGeometry()).adjusted(SCREEN_MARGIN, SCREEN_MARGIN, -SCREEN_MARGIN, -SCREEN_MARGIN)
+    decoration = known_frame_margins(widget, platform_name)
+    width = max(1, available.width() - decoration.left() - decoration.right())
+    height = max(1, available.height() - decoration.top() - decoration.bottom())
+    widget.setMinimumSize(min(minimum_width, width), min(minimum_height, height))
+    widget.resize(min(widget.width(), width), min(widget.height(), height))
+    if not window_placement(platform_name).requests_position:
+        return
+    margins = known_frame_margins(widget, platform_name)
+    position = frame_position_inside(widget.geometry().marginsAdded(margins), available)
+    # While the widget's copy of its frame is still its client area, Qt places the client area at the position it is
+    # given and the window system adds the title bar above it (see center_window_at): move it by the margins only the
+    # native window knows, so the title bar stays inside the area.
+    if widget.frameGeometry() == widget.geometry():
+        position += QPoint(margins.left(), margins.top())
+    widget.move(position)
+
+
+def known_frame_margins(window: QWidget, platform_name: str = "") -> QMargins:
+    """Return the title bar and borders the window system already gave a window, or no margin while it has given none.
+
+    The widget keeps its own copy of its frame, refreshed only when the window is moved or resized. On the platforms of
+    NATIVE_FRAME_MARGIN_PLATFORM_NAME_SET, a title bar created after that (drawn by Qt itself under Wayland once the
+    window is shown, or built late by AppKit on macOS) leaves the copy equal to the client area while the native window
+    already knows its margins, so those are read then. Elsewhere only the copy counts, and a window not decorated yet
+    reports no margin. ``platform_name`` is Qt's platform name, read from Qt when not given.
+    """
+    from PySide6.QtCore import QMargins
+    from PySide6.QtGui import QGuiApplication
+
+    frame = window.frameGeometry()
+    client = window.geometry()
+    if frame != client:
+        return QMargins(max(0, client.left() - frame.left()), max(0, client.top() - frame.top()), max(0, frame.right() - client.right()),
+                        max(0, frame.bottom() - client.bottom()))
+    if (platform_name or QGuiApplication.platformName()) not in NATIVE_FRAME_MARGIN_PLATFORM_NAME_SET:
+        return QMargins()
+    native_window = window.windowHandle()
+    if native_window is None:
+        return QMargins()
+    return native_window.frameMargins()
+
+
+def frame_position_inside(frame: QRect, available: QRect) -> QPoint:
+    """Return the top-left corner that keeps a window frame inside the usable area, moving it as little as possible."""
+    from PySide6.QtCore import QPoint
+
+    left = min(max(frame.left(), available.left()), available.right() - frame.width() + 1)
+    top = min(max(frame.top(), available.top()), available.bottom() - frame.height() + 1)
+    return QPoint(left, top)
+
+
+# Names of Qt's platform plugins, as QGuiApplication.platformName() gives them; not the sys.platform values above.
+# Qt's name for the macOS window system.
+MACOS_PLATFORM_NAME = "cocoa"
+WINDOWS_PLATFORM_NAME = "windows"
+# Qt's name for the X11 window system.
+X11_PLATFORM_NAME = "xcb"
+# Qt's name for the Wayland window system.
+WAYLAND_PLATFORM_NAME = "wayland"
+# Platforms where the widget's copy of a window's frame can stay its client area while the native window already knows
+# its title bar: AppKit can build the frame after Qt took the window's first geometry, and under Wayland Qt draws the
+# title bar itself once the window is shown. There the native window's margins are read; elsewhere only the widget's
+# copy counts, and while it is empty the title bar of a decorated window is borrowed.
+NATIVE_FRAME_MARGIN_PLATFORM_NAME_SET = frozenset({MACOS_PLATFORM_NAME, WAYLAND_PLATFORM_NAME})
+
+
+class WindowPlacement(Enum):
+    """Who places a new GitPane window on one Qt platform."""
+
+    CENTRED_ON_ANCHOR = "centred-on-anchor"
+    LEFT_TO_COMPOSITOR = "left-to-compositor"
+
+    @property
+    def requests_position(self) -> bool:
+        """Tell whether GitPane moves its windows itself; a compositor that places them ignores any position GitPane asks for."""
+        return self is WindowPlacement.CENTRED_ON_ANCHOR
+
+    @property
+    def size_waits_for_compositor_answer(self) -> bool:
+        """Tell whether a size asked just after a window is shown must wait for the compositor's answer to that show.
+
+        A compositor that places the windows answers the first show with a size of its own, the one it knew at that
+        moment, and the toolkit applies it: a size asked before that answer is overwritten for good.
+        """
+        return self is WindowPlacement.LEFT_TO_COMPOSITOR
+
+
+DEFAULT_WINDOW_PLACEMENT = WindowPlacement.CENTRED_ON_ANCHOR
+# Under Wayland the compositor places every top-level window and Qt drops the position a program asks for, so GitPane
+# only sizes its windows there and asks for no position.
+WINDOW_PLACEMENT_BY_PLATFORM_NAME: dict[str, WindowPlacement] = {
+    WAYLAND_PLATFORM_NAME: WindowPlacement.LEFT_TO_COMPOSITOR,
+}
+
+
+def window_placement(platform_name: str = "") -> WindowPlacement:
+    """Return who places GitPane's windows on a Qt platform, so the placement code only asks for positions where they are taken.
+
+    ``platform_name`` is Qt's platform name, read from Qt when not given; a platform missing from the table keeps the
+    default, where GitPane centres its windows itself.
+    """
+    from PySide6.QtGui import QGuiApplication
+
+    return WINDOW_PLACEMENT_BY_PLATFORM_NAME.get(platform_name or QGuiApplication.platformName(), DEFAULT_WINDOW_PLACEMENT)
+
+# Style GitPane runs on every system, and the legacy Windows default style it replaces there.
+FUSION_STYLE_NAME = "Fusion"
+LEGACY_WINDOWS_STYLE_NAME = "windowsvista"
+
+
+def unknown_decoration_estimate(window: QWidget, decoration_reference: QWidget | None, platform_name: str = "") -> QMargins:
+    """Estimate the title bar and borders that a window's frame does not count yet, so placing the frame leaves room for them.
+
+    Windows gives Qt a window's frame before the window is shown; an X11 window manager only adds it once the window is
+    mapped, so until then the frame equals the client area and the title bar is borrowed from a decorated window. On
+    macOS the native window knows its title bar from its creation, but Qt's copy of it in the widget can stay empty: a
+    window that got its first geometry before AppKit had built its frame keeps a frame equal to its client area until
+    the window system next moves or resizes it. Centring that frame puts the client area where the frame should be,
+    and macOS then adds the title bar above it. Under Wayland Qt draws the title bar itself after the window is shown,
+    with the same stale copy. So on macOS and under Wayland the native window's own margins are used; nothing is ever
+    borrowed from another window on macOS, while under Wayland a window not decorated yet still borrows. The estimate
+    is empty whenever the frame is already known or the window has no decoration. ``platform_name`` is Qt's platform
+    name, read from Qt when not given.
+    """
+    from PySide6.QtCore import QMargins, Qt
+    from PySide6.QtGui import QGuiApplication
+    from shiboken6 import isValid
+
+    if window.frameGeometry() != window.geometry() or window.windowFlags() & Qt.WindowType.FramelessWindowHint:
+        return QMargins()
+    platform_name = platform_name or QGuiApplication.platformName()
+    if platform_name in NATIVE_FRAME_MARGIN_PLATFORM_NAME_SET:
+        native_margins = known_frame_margins(window, platform_name)
+        # The macOS native window knows its title bar from its creation: empty margins there mean nothing to add yet,
+        # and a title bar borrowed from another window would place the window too low.
+        if not native_margins.isNull() or platform_name == MACOS_PLATFORM_NAME:
+            return native_margins
+    if decoration_reference is None or not isValid(decoration_reference):
+        return QMargins()
+    reference_frame = decoration_reference.frameGeometry()
+    reference_client = decoration_reference.geometry()
+    return QMargins(max(0, reference_client.left() - reference_frame.left()), max(0, reference_client.top() - reference_frame.top()),
+                    max(0, reference_frame.right() - reference_client.right()), max(0, reference_frame.bottom() - reference_client.bottom()))
+
+
+def uncounted_decoration_estimate(window: QWidget, decoration_reference: QWidget | None, platform_name: str = "") -> QMargins:
+    """Estimate the title bar and borders that ``known_frame_margins`` does not count yet, to take off a usable area a size is fitted in.
+
+    The size fits (``fit_window``, the largest client size) already take off the margins the window system gave,
+    including those only the native window knows. Taking the full estimate off the area as well would count such a
+    title bar twice and leave the window shorter by its height, so the estimate only applies while no margin is known.
+    """
+    from PySide6.QtCore import QMargins
+
+    if not known_frame_margins(window, platform_name).isNull():
+        return QMargins()
+    return unknown_decoration_estimate(window, decoration_reference, platform_name)
+
+
+def center_window_at(window: QWidget, centre: QPoint, screen: QScreen, decoration_reference: QWidget | None = None, *, platform_name: str = "") -> None:
+    """Put the window's frame centre on a point, then pull the frame back inside the screen's usable area if it crosses an edge.
+
+    Frames are compared, not client areas, so the title bar counts as part of the window; the current frame size is used.
+    While the window system has not told the frame yet (X11 before the first map), ``decoration_reference`` lends its
+    title bar and borders: Qt then places the client area at the position it is given and the window manager adds the
+    title bar above it, so the client area is moved down by that estimate. Where the compositor places windows itself,
+    nothing is moved: it would ignore the position. ``platform_name`` is Qt's platform name, read from Qt when not given.
+    """
+    from PySide6.QtCore import QPoint
+
+    if not window_placement(platform_name).requests_position:
+        return
+    available = screen.availableGeometry().adjusted(SCREEN_MARGIN, SCREEN_MARGIN, -SCREEN_MARGIN, -SCREEN_MARGIN)
+    decoration = unknown_decoration_estimate(window, decoration_reference, platform_name)
+    frame = window.frameGeometry().marginsAdded(decoration)
+    frame.moveCenter(centre)
+    window.move(frame_position_inside(frame, available) + QPoint(decoration.left(), decoration.top()))