zettcode-app 0.4.2__py3-none-any.whl

zettcode/app/ui/clipboard.py

@@ -0,0 +1,340 @@
+"""Read an image off the system clipboard, or out of a paste.
+
+A terminal cannot hand an application the bytes of a pasted image, so the shell
+asks the desktop instead. macOS hands the pasteboard over in-process through the
+Objective-C runtime, with ``osascript`` kept as the fallback that can coerce a
+format the pasteboard does not store directly; Linux asks ``wl-paste`` or
+``xclip`` for whichever image type the clipboard advertises. A machine with
+neither tool — or a clipboard holding text — simply has no image to attach, and
+a terminal that pastes the picture *as text* instead (VS Code sends base64) is
+covered by :func:`image_from_paste` further down.
+
+The bytes are read back into memory, because that is what the runtime's
+multimodal message wants: nothing is left behind in the workspace.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import ctypes
+import ctypes.util
+import re
+import subprocess
+import sys
+import tempfile
+from collections.abc import Callable, Sequence
+from ctypes import c_char_p, c_ulong, c_void_p
+from functools import lru_cache
+from pathlib import Path
+from subprocess import CompletedProcess
+from typing import Any, TypeAlias
+
+#: What one clipboard command looks like: argv in, its result out.
+Runner: TypeAlias = Callable[[Sequence[str]], CompletedProcess[bytes]]
+
+#: Media type of an image the desktop path had to normalise: PNG is what both
+#: platforms write, and the conversion on macOS exists to keep that true.
+PNG = "image/png"
+
+#: The image types a multimodal message accepts, and the bytes each one starts
+#: with. A clipboard can offer more formats than this; the rest are ignored
+#: rather than sent to a model that would reject them.
+SIGNATURES: tuple[tuple[bytes, str], ...] = (
+    (b"\x89PNG\r\n\x1a\n", "image/png"),
+    (b"\xff\xd8\xff", "image/jpeg"),
+    (b"GIF87a", "image/gif"),
+    (b"GIF89a", "image/gif"),
+)
+
+#: macOS pasteboard flavours, preferred first. ``PNGf`` is what a screenshot is;
+#: a browser often offers only TIFF. Asking the system for a flavour makes it
+#: coerce whatever it holds, so a HEIC or BMP screen capture still arrives as a
+#: PNG.
+_MACOS_FLAVOURS = ("PNGf", "TIFF")
+
+#: Pasteboard types read straight out of the running process, most widely
+#: accepted first. ``dataForType:`` returns a type only when it is really there,
+#: which is what makes this path fast but incomplete: anything else falls back
+#: to AppleScript, which coerces.
+_PASTEBOARD_UTIS = ("public.png", "public.jpeg", "public.webp", "com.compuserve.gif", "public.tiff")
+
+#: The magic bytes a TIFF starts with, either endianness.
+_TIFF_SIGNATURES = (b"II*\x00", b"MM\x00*")
+
+#: ``osascript`` prints AppleScript data as ``«data <four-char code><hex>»``.
+_APPLE_DATA = re.compile(r"^«data [0-9A-Za-z]{4}([0-9A-Fa-f]+)»$")
+
+#: Image types tried on Linux, most widely accepted first.
+_LINUX_TYPES = ("image/png", "image/jpeg", "image/webp", "image/gif")
+
+#: A ``data:`` URI that carries an image as base64, the way a page or an editor
+#: copies one into a text clipboard.
+_DATA_URI = re.compile(r"^data:image/[\w.+-]+;base64,", re.IGNORECASE)
+
+#: Shorter base64 cannot hold a real image, so it is left as text even when it
+#: happens to decode.
+_MIN_BASE64 = 64
+
+
+def read_image(*, runner: Runner | None = None, system: str | None = None) -> tuple[bytes, str] | None:
+    """Return the clipboard's image as ``(bytes, media type)``, or None.
+
+    Args:
+        runner: Runs one clipboard command; injectable so tests can describe a
+            desktop instead of owning one. Injecting one also keeps the
+            in-process macOS pasteboard reader out of the way, so a test never
+            depends on the machine's real clipboard.
+        system: Platform to read from; ``sys.platform`` by default.
+    """
+    run = _run if runner is None else runner
+    platform = sys.platform if system is None else system
+    if platform == "darwin":
+        return _macos_image(run, native=runner is None)
+    if platform.startswith("linux"):
+        return _x11_image(run)
+    return None
+
+
+#: Seconds a clipboard tool may take. The read happens on the event loop, in a key handler, so a
+#: tool that never answers — ``xclip`` against a forwarded X display whose connection went away
+#: is the usual one — would freeze the whole interface; a few seconds is far longer than a
+#: working one needs.
+TOOL_TIMEOUT = 3.0
+
+
+def _run(argv: Sequence[str]) -> CompletedProcess[bytes]:
+    """Run one clipboard command, capturing its output; any failure is a nonzero result.
+
+    The callers read ``returncode`` and nothing else, and they cannot tell a tool that ran and
+    found nothing from a tool that could not run, so neither is an exception. That is not a
+    detail: ``subprocess.run`` reports a missing executable by *raising*, not by returning
+    nonzero, so a server with neither ``wl-paste`` nor ``xclip`` — most of them — used to take
+    the whole session down on the first Ctrl-V.
+
+    Returns:
+        The finished process; ``127`` when the program is not there or cannot be run, ``124``
+        when it did not answer in time (the codes a shell uses for the same two things).
+    """
+    try:
+        return subprocess.run(list(argv), capture_output=True, check=False, timeout=TOOL_TIMEOUT)
+    except subprocess.TimeoutExpired:
+        return CompletedProcess(list(argv), 124, b"", b"timed out")
+    except OSError as error:
+        # The tool is named here rather than left to the error's own text: POSIX puts the file name
+        # in a FileNotFoundError and Windows ("[WinError 2] The system cannot find the file
+        # specified") does not, and a reason that does not say which tool is not much of one.
+        return CompletedProcess(list(argv), 127, b"", f"{argv[0]}: {error}".encode())
+
+
+def _macos_image(runner: Runner, *, native: bool) -> tuple[bytes, str] | None:
+    """Return whatever picture the pasteboard holds, fastest way first.
+
+    The in-process reader hands back a flavour exactly as it is stored, which
+    takes about a millisecond. AppleScript is asked only when that finds
+    nothing, because its clipboard coercion also covers formats the pasteboard
+    does not expose as a raw type — a HEIC or BMP capture — at the price of
+    starting a helper program.
+    """
+    if native:
+        reader = _pasteboard_reader()
+        if reader is not None:
+            data = reader()
+            if data is not None:
+                image = _image_from_bytes(data, runner)
+                if image is not None:
+                    return image
+                # Data of a flavour this build cannot read: let AppleScript
+                # coerce it rather than reporting no picture at all.
+    return _script_image(runner)
+
+
+def _script_image(runner: Runner) -> tuple[bytes, str] | None:
+    """Ask AppleScript for the clipboard's picture and sniff what comes back.
+
+    AppleScript is asked for the *data*, not told to write a file: ``write``
+    copies a multi-megabyte image through AppleScript's own file API and takes
+    seconds, while ``get the clipboard as`` returns it in one step.
+    """
+    for flavour in _MACOS_FLAVOURS:
+        data = _apple_data(runner, flavour)
+        if data is None:
+            continue
+        image = _image_from_bytes(data, runner)
+        if image is not None:
+            return image
+    return None
+
+
+def _image_from_bytes(data: bytes, runner: Runner) -> tuple[bytes, str] | None:
+    """Return the image these bytes are, converting a TIFF the model will not take."""
+    sniffed = _sniff(data)
+    if sniffed is not None:
+        return sniffed
+    if data.startswith(_TIFF_SIGNATURES):
+        return _convert_tiff(runner, data)
+    return None
+
+
+def _apple_data(runner: Runner, flavour: str) -> bytes | None:
+    """Return one clipboard flavour as raw bytes, or None when it is absent."""
+    result = runner(["osascript", "-e", f"get the clipboard as \u00abclass {flavour}\u00bb"])
+    if result.returncode != 0:
+        return None
+    # The guillemets around the data are non-ASCII, so this is UTF-8, not ASCII.
+    match = _APPLE_DATA.match(result.stdout.decode("utf-8", "replace").strip())
+    if match is None:
+        return None
+    try:
+        return bytes.fromhex(match.group(1))
+    except ValueError:
+        return None
+
+
+def _convert_tiff(runner: Runner, data: bytes) -> tuple[bytes, str] | None:
+    """Turn a TIFF the clipboard offered into a PNG the model will take."""
+    with tempfile.TemporaryDirectory(prefix="zettcode-clipboard-") as directory:
+        source = Path(directory) / "clipboard.tiff"
+        source.write_bytes(data)
+        converted = Path(directory) / "converted.png"
+        if runner(["sips", "-s", "format", "png", str(source), "--out", str(converted)]).returncode != 0:
+            return None
+        if not converted.is_file():
+            return None
+        return converted.read_bytes(), PNG
+
+
+@lru_cache(maxsize=1)
+def _pasteboard_reader() -> Callable[[], bytes | None] | None:
+    """Return the in-process macOS pasteboard reader, binding it on first use.
+
+    ``osascript`` costs a third of a second even for a tiny picture — the
+    helper program and AppleScript's clipboard coercion are the price, not the
+    bytes — while the Objective-C runtime is already in the process. Nothing is
+    guaranteed to be there, so a reader that cannot be bound is ``None`` and
+    the caller falls back to the script.
+    """
+    if sys.platform != "darwin":
+        return None
+    library = ctypes.util.find_library("objc")
+    if library is None:
+        return None
+    try:
+        runtime = ctypes.CDLL(library)
+        # AppKit has to be loaded before its classes can be looked up.
+        ctypes.CDLL("/System/Library/Frameworks/AppKit.framework/AppKit")
+        runtime.objc_getClass.restype = c_void_p
+        runtime.objc_getClass.argtypes = [c_char_p]
+        runtime.sel_registerName.restype = c_void_p
+        runtime.sel_registerName.argtypes = [c_char_p]
+        runtime.objc_autoreleasePoolPush.restype = c_void_p
+        runtime.objc_autoreleasePoolPush.argtypes = []
+        runtime.objc_autoreleasePoolPop.restype = None
+        runtime.objc_autoreleasePoolPop.argtypes = [c_void_p]
+    except (AttributeError, OSError):
+        return None
+
+    def send(
+        receiver: Any, selector: bytes, *args: Any, restype: Any = c_void_p, argtypes: tuple[Any, ...] = ()
+    ) -> Any:
+        """Send one Objective-C message with the signature that call needs."""
+        runtime.objc_msgSend.restype = restype
+        runtime.objc_msgSend.argtypes = (c_void_p, c_void_p, *argtypes)
+        return runtime.objc_msgSend(receiver, runtime.sel_registerName(selector), *args)
+
+    def read() -> bytes | None:
+        """Return the first image flavour the pasteboard holds, or None."""
+        # Autoreleased objects — the NSData that is handed back, the strings
+        # asked for — are freed here instead of piling up in a long-running
+        # process with no pool of its own.
+        pool = runtime.objc_autoreleasePoolPush()
+        try:
+            board = send(runtime.objc_getClass(b"NSPasteboard"), b"generalPasteboard")
+            for uti in _PASTEBOARD_UTIS:
+                name = send(
+                    runtime.objc_getClass(b"NSString"),
+                    b"stringWithUTF8String:",
+                    uti.encode(),
+                    argtypes=(c_char_p,),
+                )
+                data = send(board, b"dataForType:", name, argtypes=(c_void_p,))
+                if not data:
+                    continue
+                length = send(data, b"length", restype=c_ulong)
+                return ctypes.string_at(send(data, b"bytes"), length)
+            return None
+        finally:
+            runtime.objc_autoreleasePoolPop(pool)
+
+    return read
+
+
+def _x11_image(runner: Runner) -> tuple[bytes, str] | None:
+    """Read the first image an X11 or Wayland clipboard offers.
+
+    ``wl-paste`` needs a Wayland session and ``xclip`` an X server, so both are
+    tried. Each clipboard advertises the types it holds, which is what lets a
+    JPEG or WebP be read as itself instead of being asked for a PNG and giving
+    up; a tool that cannot list types is still asked for PNG.
+    """
+    for base, list_argv, flag in (
+        (["wl-paste", "--no-newline"], ["wl-paste", "--list-types"], "--type"),
+        (
+            ["xclip", "-selection", "clipboard", "-o"],
+            ["xclip", "-selection", "clipboard", "-t", "TARGETS", "-o"],
+            "-t",
+        ),
+    ):
+        for media_type in _offered_types(runner, list_argv) or (PNG,):
+            if media_type not in _LINUX_TYPES:
+                continue
+            result = runner([*base, flag, media_type])
+            if result.returncode != 0 or not result.stdout:
+                continue
+            return _sniff(result.stdout) or (result.stdout, media_type)
+    return None
+
+
+def _offered_types(runner: Runner, argv: Sequence[str]) -> tuple[str, ...]:
+    """Return the image types a clipboard tool says are on the clipboard."""
+    result = runner(argv)
+    if result.returncode != 0:
+        return ()
+    text = result.stdout.decode("utf-8", "replace")
+    return tuple(line.strip() for line in text.splitlines() if line.strip().startswith("image/"))
+
+
+def image_from_paste(text: str) -> tuple[bytes, str] | None:
+    """Return the image a pasted payload carries, if it carries one.
+
+    A terminal cannot paste an image as bytes, but it can paste one as text:
+    VS Code turns a clipboard image into base64, warns about the size, and
+    sends the characters, and a copied ``data:image/...;base64,`` URI is the
+    same idea. Recognising both turns one paste key into the same ``[image #N]``
+    chip as :func:`read_image`, instead of a wall of characters standing in for
+    a picture.
+
+    Only a payload whose decoded bytes start like a known image format counts,
+    so ordinary text that merely looks like base64 stays text.
+    """
+    payload = text.strip()
+    if _DATA_URI.match(payload):
+        payload = payload.split(",", 1)[1]
+    payload = "".join(payload.split())
+    if len(payload) < _MIN_BASE64:
+        return None
+    try:
+        data = base64.b64decode(payload, validate=True)
+    except (binascii.Error, ValueError):
+        return None
+    return _sniff(data)
+
+
+def _sniff(data: bytes) -> tuple[bytes, str] | None:
+    """Return ``data`` and its media type when it starts like a known image."""
+    for signature, media_type in SIGNATURES:
+        if data.startswith(signature):
+            return data, media_type
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return data, "image/webp"
+    return None

zettcode/app/ui/commands.py

@@ -0,0 +1,323 @@
+"""The shell's own slash commands: the ones that preview as they are walked or edit a form of their own.
+
+They live outside :class:`~zettcode.app.ui.app.ZettCodeApp` so that class stays
+the wiring \u2014 widget tree, keymap, pages \u2014 rather than the command set. Every
+handler is a method here, returns a
+:class:`~zettcode.plugin_api.commands.CommandResult`, and never paints directly: the
+shell applies the result (see ``ZettCodeApp._apply_result``).
+
+The commands that only need the shell's narrow public surface (``/resume``, ``/model``, ``/context`` and the rest)
+are built-in plugins instead, in :mod:`zettcode.commands.handlers`. What stays here is what cannot be written
+against that surface yet: ``/theme`` and ``/pet`` call the shell's previews as the menu is walked, and ``/config``
+and ``/statusline`` open panels that edit state the shell owns; self-compaction is a `/plugins` switch now.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from zettcode.config_edit import ConfigEditError
+from zettcode.plugin_api.commands import (
+    Command,
+    CommandContext,
+    CommandProvider,
+    CommandResult,
+    Subcommand,
+    subcommand_words,
+)
+from zettcode.presenters.statusline import NAMES, Part
+
+from .widgets import (
+    PetPage,
+    StatuslinePage,
+    bottom_panel,
+    pet_rows,
+    statusline_rows,
+)
+
+#: One-line description per built-in palette, shown next to its name.
+THEME_NOTES = {
+    "dark": "green-leaning palette for dark terminals",
+    "light": "green-leaning palette for light terminals",
+}
+
+#: What ``/config`` takes first, as its description lists them.
+CONFIG_WORDS = (
+    Subcommand("add", "add a model: a provider, then what it needs", needs_more=True),
+    Subcommand("remove", "remove a model by number or name", needs_more=True),
+    Subcommand("list", "show the models in the file"),
+    Subcommand("providers", "show the providers and where to get a key"),
+)
+
+
+def _missing_file(error: BaseException) -> bool:
+    """Return whether a failed write failed because there is no file yet, however deeply the error was wrapped.
+
+    The file editor raises ``ConfigEditError("… does not exist") from`` the ``FileNotFoundError``, and the SDK
+    wraps that again in ``ConfigurationError``, so the cause is the only reliable part of the answer. Note what
+    this cannot tell apart: a *read* of a missing file inside a directory that cannot be written also raises
+    ``FileNotFoundError``, so the machine is promised a file that ``/config`` will then fail to write — with its
+    own error, which is the one place that knows why.
+    """
+    seen: set[int] = set()
+    current: BaseException | None = error
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        if isinstance(current, FileNotFoundError):
+            return True
+        current = current.__cause__ or current.__context__
+    return False
+
+
+if TYPE_CHECKING:  # pragma: no cover - only needed for the annotation
+    from .app import ZettCodeApp
+
+
+class ShellCommands(CommandProvider):
+    """The commands the shell keeps for itself.
+
+    It is one provider among several: the shell merges it with the built-in plugins' commands, the agent's and the
+    installed plugins' through a registry, so every source of commands is the same shape and the first to claim a
+    name wins.
+    """
+
+    def __init__(self, shell: ZettCodeApp) -> None:
+        """Keep the shell the handlers act on; ``shell.app`` is its ``TuiApp``."""
+        self.shell = shell
+
+    @property
+    def items(self) -> Sequence[Command]:
+        """Return the shell's own commands, in the order ``/help`` lists them."""
+        return (
+            # ``when_busy="now"`` below is for what only looks at the session or sets something the
+            # running request reads when it needs it. What it touches while a request runs - the
+            # transcript it writes into, the session, the model it started with and the window that
+            # model's compaction is sized to - stays refused: /config, and the plugins' /model, /clear,
+            # /resume, /fork, plus the agent's /new, /compact and /export.
+            Command(
+                "/config",
+                "add, change or remove models: /config [add|remove|list|providers]",
+                "app",
+                self.config,
+                subcommands=CONFIG_WORDS,
+            ),
+            Command(
+                "/theme",
+                "choose the palette: /theme <name> (the menu previews each)",
+                "app",
+                self.theme,
+                when_busy="now",
+                subcommands=self.theme_words,
+                preview=self.shell.preview_theme,
+            ),
+            Command(
+                "/pet",
+                "choose the pet: /pet opens a panel, /pet <name> picks one",
+                "app",
+                self.pet,
+                when_busy="now",
+            ),
+            Command(
+                "/statusline",
+                "choose which parts of the header and status line show: /statusline opens a panel",
+                "app",
+                self.statusline,
+                when_busy="now",
+            ),
+        )
+
+    def _offer(self, command: str) -> CommandResult:
+        """Put the command and a space in the draft, which opens the menu of the words it takes.
+
+        A command that is a choice among a few fixed words has no page of its own: the menu is the choice,
+        so typing the bare command only moves the reader to it.
+        """
+        self.shell.offer(command)
+        return CommandResult()
+
+    def theme_words(self) -> tuple[Subcommand, ...]:
+        """Offer every palette by name: the built-in ones, then the plugins' and the reader's own, with their notes."""
+        catalog = self.shell.agent.themes
+        notes = {**THEME_NOTES, **catalog.notes()}
+        return subcommand_words(catalog.names(), notes, self.shell.app.theme.name)
+
+    async def config(self, context: CommandContext) -> CommandResult:
+        """Open the model list, or act on it from one line.
+
+        With nothing after it the command opens the panel, which asks one question at a time and
+        is the way to type a token without it being echoed. The words after it do the same job
+        on one line: ``add`` takes a provider and whatever of its settings the line gives, and
+        asks for the rest; ``remove`` takes a number or a name; ``list`` and ``providers`` only
+        show. A refusal \u2014 a bad address, a file that cannot be edited \u2014 is the command's error and
+        nothing is written.
+        """
+        word, _, rest = context.argument.partition(" ")
+        shell = self.shell
+        if not word:
+            return CommandResult(widget=shell.config_page())
+        if word == "list":
+            return CommandResult(message=shell.config_listing())
+        if word == "providers":
+            return CommandResult(message=shell.config_providers_listing())
+        if word == "add":
+            done = shell.config_add_from_line(rest)
+            return CommandResult(notification=done, relayout=True) if done else CommandResult()
+        if word == "remove":
+            return CommandResult(notification=shell.config_remove_from_line(rest), relayout=True)
+        raise ValueError("Usage: /config [add <provider> ... | remove <number|name> | list | providers]")
+
+    async def theme(self, context: CommandContext) -> CommandResult:
+        """Switch straight to a named palette and remember it, or open the menu of them.
+
+        The choice is written to ``[ui] theme`` in the config file so the next start opens in it. A file that
+        cannot take the line does not undo the switch: the palette is on, and the reader is told it will not be
+        there next time and why.
+        """
+        if not context.argument:
+            return self._offer("/theme")
+        name = context.argument.strip()
+        self.shell.apply_theme(name)
+        try:
+            self.shell.agent.remember_theme(name)
+        except ConfigEditError as error:
+            self._unkept(f"theme {name}", error, applied=True)
+            return CommandResult(relayout=True)
+        return CommandResult(relayout=True, notification=f"theme {name} \u2014 remembered for next time")
+
+    async def pet(self, context: CommandContext) -> CommandResult:
+        """Open the panel of pets, or switch straight to a named one; either way the choice is remembered.
+
+        The panel lists the pets with the marked one shown beside the list and over the conversation; Enter
+        chooses and Escape puts the old one back. The choice is written to ``[ui] pet`` in the config file so the
+        next start opens with it. A file that cannot take the line does not undo the switch: the pet is there,
+        and the reader is told it will not be next time and why. A pet that is switched off in ``/statusline`` is
+        still chosen, and the reader is told why nothing appeared. With no pet offered at all, either way, the reader
+        is told that and why, instead of being shown a panel with nothing in it or an "unknown pet" for a name that
+        could never exist.
+        """
+        shell = self.shell
+        if not shell.agent.pets.names():
+            # No plugin offers a pet: there is nothing to choose from, and a panel of no rows has nowhere for the mark
+            # to stand. What the reader can do depends on why, so the config says which of the two it is.
+            if shell.agent.pets_switched_off:
+                return CommandResult(message="The pets plugin is switched off. Turn it on with /plugins.")
+            return CommandResult(message="No pets are installed. They come with the program: reinstall zettcode.")
+        if not context.argument:
+
+            def choose(name: str) -> None:
+                shell.close_page()
+                try:
+                    shell.apply_pet(name)
+                    shell.agent.remember_pet(name)
+                except ConfigEditError as error:
+                    # Before ValueError: the file editor's refusal is a ValueError too, and it is the one a
+                    # machine with no file yet should hear about without the word "failure".
+                    self._unkept(f"pet {name}", error, applied=True)
+                    return
+                except ValueError as error:
+                    shell.transcript.error(str(error))
+                    return
+                shell.transcript.notice(self._pet_chosen(name))
+
+            def cancel() -> None:
+                shell.preview_pet(None)
+                shell.close_page()
+
+            catalog = shell.agent.pets
+            page = PetPage(catalog, shell.pet.pet.name, on_move=shell.preview_pet, on_select=choose, on_cancel=cancel)
+            return CommandResult(widget=bottom_panel(page, rows=pet_rows(len(catalog.names()), shell.app.height)))
+        name = context.argument.strip()
+        shell.apply_pet(name)
+        try:
+            shell.agent.remember_pet(name)
+        except ConfigEditError as error:
+            self._unkept(f"pet {name}", error, applied=True)
+            return CommandResult(relayout=True)
+        return CommandResult(relayout=True, notification=self._pet_chosen(name))
+
+    def _pet_chosen(self, name: str) -> str:
+        """Say which pet was chosen, and why nothing shows if the reader has switched the pet off."""
+        if "pet" in self.shell.agent.statusline_hidden:
+            return f"pet {name} \u2014 remembered, but the pet is hidden: /statusline show pet"
+        return f"pet {name} \u2014 remembered for next time"
+
+    def _unwritten_config(self, what: str, error: Exception, *, applied: bool) -> str | None:
+        """Return the sentence for a setting the missing file could not keep, or ``None`` when it is another failure.
+
+        A machine that has never been set up has no config file at all, and none of the commands that write one
+        line creates it: a file holding a palette and no models is worse than none, and ``/config`` is what writes
+        it. So on that machine the line names what brings the file rather than reporting a missing file as a
+        failure, and the branch is chosen on *why* the write failed — a file that is not there, however deeply the
+        error was wrapped — rather than on what the path looks like now.
+
+        Args:
+            what: The setting, as a noun phrase the sentence can start with ("theme nord", "the status line").
+            error: What the write raised; anything not caused by a missing file is the caller's failure to report.
+            applied: Whether the change is in force for this run. ``/theme`` and ``/pet`` apply before they write,
+                so they are on now; the compaction default and the status line write first and are not, and their
+                sentence must not claim a change the run does not have. ``/config`` writes the models, not this
+                setting, so what it brings is the file the setting can be saved into.
+        """
+        if self.shell.model is not None or not _missing_file(error):
+            return None
+        path = self.shell.client.config_file
+        if applied:
+            return f"{what} is on for this run; it is kept for next time once `/config` writes {path}"
+        return f"{what} is not saved; `/config` writes {path}, and it can be set again then"
+
+    def _unkept(self, what: str, error: Exception, *, applied: bool) -> None:
+        """Say what became of a setting the file could not keep: a notice on a fresh machine, else the failure.
+
+        The failure follows ``applied`` for the same reason the fresh branch does: "will not be remembered" says
+        the change is in force and only its memory failed, which is untrue of the pair that writes first.
+        """
+        unwritten = self._unwritten_config(what, error, applied=applied)
+        if unwritten is not None:
+            self.shell.transcript.notice(unwritten)
+        elif applied:
+            self.shell.transcript.error(f"{what} will not be remembered: {error}")
+        else:
+            self.shell.transcript.error(f"{what} is not saved: {error}")
+
+    def _or_reason(self, what: str, error: Exception, *, applied: bool) -> str:
+        """The sentence a command reports a failed setting with: the fresh machine's, or what became of it."""
+        unwritten = self._unwritten_config(what, error, applied=applied)
+        if unwritten is not None:
+            return unwritten
+        return f"{what} will not be remembered: {error}" if applied else f"{what} is not saved: {error}"
+
+    async def statusline(self, context: CommandContext) -> CommandResult:
+        """Hide or show parts from the words it takes, or open the panel with a switch for each part.
+
+        The switches only move; Enter writes ``[statusline]`` into the config file, and the rows follow at
+        the next paint. Escape applies nothing. A config file that cannot be written is reported and the rows
+        stay as they were.
+        """
+        shell = self.shell
+        if context.argument:
+            try:
+                message = shell.agent.change_statusline(context.argument)
+            except ConfigEditError as error:
+                return CommandResult(message=self._or_reason("The status line", error, applied=False))
+            except ValueError as error:
+                return CommandResult(message=str(error))
+            return CommandResult(message=message, relayout=True)
+
+        def apply(shown: dict[str, bool]) -> None:
+            shell.close_page()
+            try:
+                shell.agent.remember_statusline(shown)
+            except ConfigEditError as error:
+                # Written before it applies, like the compaction default: the sentence says it is not saved.
+                self._unkept("The status line", error, applied=False)
+                return
+            except ValueError as error:
+                shell.transcript.error(str(error))
+                return
+            shell.transcript.notice(shell.agent.statusline_summary())
+
+        # The program's own items are in the panel already; a plugin's are added beside them.
+        extra = tuple(Part(item.name, item.summary) for item in shell.agent.turn_segments if item.name not in NAMES)
+        page = StatuslinePage(shell.agent.statusline_hidden, extra, on_apply=apply, on_cancel=shell.close_page)
+        return CommandResult(widget=bottom_panel(page, rows=statusline_rows(shell.app.height)))