code-puppy-core-plugins 0.0.2__py3-none-any.whl

code_puppy_core_plugins/puppy_spinner/builtin_frames.py

@@ -0,0 +1,172 @@
+"""Frame data for the catalogue's cli-spinners-style builtins.
+
+GENERATED data module -- every non-ASCII char is escape-spelled (repo
+emoji filter), which is also why this file is data-only: hand-editing
+escaped braille is nobody's idea of fun. Intervals are intentionally
+absent; ``spinners.py`` applies one normalized speed to all of these.
+"""
+
+# Frame rows are packed several-per-line; one-per-line would blow the
+# 600-line cap. The bare marker below must stay bare -- ruff ignores
+# 'fmt: off' comments that have trailing prose.
+# fmt: off
+# name -> (frames, description)
+EXTRA_SPECS = {
+    "dotsWide": (
+        (
+            "\u2809\u2809", "\u2808\u2819", "\u2800\u2839", "\u2800\u28b8", "\u2800\u28f0",
+            "\u2880\u28e0", "\u28c0\u28c0", "\u28c4\u2840", "\u28c6\u2800", "\u2847\u2800",
+            "\u280f\u2800", "\u280b\u2801",
+        ),
+        "a two-cell braille orbit",
+    ),
+    "dots8Bit": (
+        (
+            "\u2800", "\u2801", "\u2802", "\u2803", "\u2804", "\u2805", "\u2806", "\u2807",
+            "\u2840", "\u2841", "\u2842", "\u2843", "\u2844", "\u2845", "\u2846", "\u2847",
+            "\u2808", "\u2809", "\u280a", "\u280b", "\u280c", "\u280d", "\u280e", "\u280f",
+            "\u2848", "\u2849", "\u284a", "\u284b", "\u284c", "\u284d", "\u284e", "\u284f",
+            "\u2810", "\u2811", "\u2812", "\u2813", "\u2814", "\u2815", "\u2816", "\u2817",
+            "\u2850", "\u2851", "\u2852", "\u2853", "\u2854", "\u2855", "\u2856", "\u2857",
+            "\u2818", "\u2819", "\u281a", "\u281b", "\u281c", "\u281d", "\u281e", "\u281f",
+            "\u2858", "\u2859", "\u285a", "\u285b", "\u285c", "\u285d", "\u285e", "\u285f",
+            "\u2820", "\u2821", "\u2822", "\u2823", "\u2824", "\u2825", "\u2826", "\u2827",
+            "\u2860", "\u2861", "\u2862", "\u2863", "\u2864", "\u2865", "\u2866", "\u2867",
+            "\u2828", "\u2829", "\u282a", "\u282b", "\u282c", "\u282d", "\u282e", "\u282f",
+            "\u2868", "\u2869", "\u286a", "\u286b", "\u286c", "\u286d", "\u286e", "\u286f",
+            "\u2830", "\u2831", "\u2832", "\u2833", "\u2834", "\u2835", "\u2836", "\u2837",
+            "\u2870", "\u2871", "\u2872", "\u2873", "\u2874", "\u2875", "\u2876", "\u2877",
+            "\u2838", "\u2839", "\u283a", "\u283b", "\u283c", "\u283d", "\u283e", "\u283f",
+            "\u2878", "\u2879", "\u287a", "\u287b", "\u287c", "\u287d", "\u287e", "\u287f",
+            "\u2880", "\u2881", "\u2882", "\u2883", "\u2884", "\u2885", "\u2886", "\u2887",
+            "\u28c0", "\u28c1", "\u28c2", "\u28c3", "\u28c4", "\u28c5", "\u28c6", "\u28c7",
+            "\u2888", "\u2889", "\u288a", "\u288b", "\u288c", "\u288d", "\u288e", "\u288f",
+            "\u28c8", "\u28c9", "\u28ca", "\u28cb", "\u28cc", "\u28cd", "\u28ce", "\u28cf",
+            "\u2890", "\u2891", "\u2892", "\u2893", "\u2894", "\u2895", "\u2896", "\u2897",
+            "\u28d0", "\u28d1", "\u28d2", "\u28d3", "\u28d4", "\u28d5", "\u28d6", "\u28d7",
+            "\u2898", "\u2899", "\u289a", "\u289b", "\u289c", "\u289d", "\u289e", "\u289f",
+            "\u28d8", "\u28d9", "\u28da", "\u28db", "\u28dc", "\u28dd", "\u28de", "\u28df",
+            "\u28a0", "\u28a1", "\u28a2", "\u28a3", "\u28a4", "\u28a5", "\u28a6", "\u28a7",
+            "\u28e0", "\u28e1", "\u28e2", "\u28e3", "\u28e4", "\u28e5", "\u28e6", "\u28e7",
+            "\u28a8", "\u28a9", "\u28aa", "\u28ab", "\u28ac", "\u28ad", "\u28ae", "\u28af",
+            "\u28e8", "\u28e9", "\u28ea", "\u28eb", "\u28ec", "\u28ed", "\u28ee", "\u28ef",
+            "\u28b0", "\u28b1", "\u28b2", "\u28b3", "\u28b4", "\u28b5", "\u28b6", "\u28b7",
+            "\u28f0", "\u28f1", "\u28f2", "\u28f3", "\u28f4", "\u28f5", "\u28f6", "\u28f7",
+            "\u28b8", "\u28b9", "\u28ba", "\u28bb", "\u28bc", "\u28bd", "\u28be", "\u28bf",
+            "\u28f8", "\u28f9", "\u28fa", "\u28fb", "\u28fc", "\u28fd", "\u28fe", "\u28ff",
+        ),
+        "all 256 braille patterns",
+    ),
+    "dotsCircle": (
+        (
+            "\u288e ", "\u280e\u2801", "\u280a\u2811", "\u2808\u2831", " \u2871",
+            "\u2880\u2870", "\u2884\u2860", "\u2886\u2840",
+        ),
+        "a braille ring chase",
+    ),
+    "sand": (
+        (
+            "\u2801", "\u2802", "\u2804", "\u2840", "\u2848", "\u2850", "\u2860", "\u28c0",
+            "\u28c1", "\u28c2", "\u28c4", "\u28cc", "\u28d4", "\u28e4", "\u28e5", "\u28e6",
+            "\u28ee", "\u28f6", "\u28f7", "\u28ff", "\u287f", "\u283f", "\u289f", "\u281f",
+            "\u285b", "\u281b", "\u282b", "\u288b", "\u280b", "\u280d", "\u2849", "\u2809",
+            "\u2811", "\u2821", "\u2881",
+        ),
+        "grains trickling through",
+    ),
+    "growVertical": (
+        (
+            "\u2581", "\u2583", "\u2584", "\u2585", "\u2586", "\u2587", "\u2586", "\u2585",
+            "\u2584", "\u2583",
+        ),
+        "a bar breathing up and down",
+    ),
+    "growHorizontal": (
+        (
+            "\u258f", "\u258e", "\u258d", "\u258c", "\u258b", "\u258a", "\u2589", "\u258a",
+            "\u258b", "\u258c", "\u258d", "\u258e",
+        ),
+        "a bar breathing side to side",
+    ),
+    "noise": (
+        (
+            "\u2593", "\u2592", "\u2591",
+        ),
+        "static from an old TV",
+    ),
+    "binary": (
+        (
+            "010010", "001100", "100101", "111010", "111101", "010111", "101011", "111000",
+            "110011", "110101",
+        ),
+        "streaming ones and zeros",
+    ),
+    "chevrons": (
+        (
+            "\u25b9\u25b9\u25b9\u25b9\u25b9", "\u25b8\u25b9\u25b9\u25b9\u25b9",
+            "\u25b9\u25b8\u25b9\u25b9\u25b9", "\u25b9\u25b9\u25b8\u25b9\u25b9",
+            "\u25b9\u25b9\u25b9\u25b8\u25b9", "\u25b9\u25b9\u25b9\u25b9\u25b8",
+        ),
+        "a pulse of chevrons",
+    ),
+    "bouncingBar": (
+        (
+            "[    ]", "[=   ]", "[==  ]", "[=== ]", "[====]", "[ ===]", "[  ==]", "[   =]",
+            "[    ]", "[   =]", "[  ==]", "[ ===]", "[====]", "[=== ]", "[==  ]", "[=   ]",
+        ),
+        "old-school loading-bar ping-pong",
+    ),
+    "bouncingBall": (
+        (
+            "( \u25cf    )", "(  \u25cf   )", "(   \u25cf  )", "(    \u25cf )", "(     \u25cf)",
+            "(    \u25cf )", "(   \u25cf  )", "(  \u25cf   )", "( \u25cf    )", "(\u25cf     )",
+        ),
+        "a ball on kennel patrol",
+    ),
+    "pong": (
+        (
+            "\u2590\u2802       \u258c", "\u2590\u2808       \u258c",
+            "\u2590 \u2802      \u258c", "\u2590 \u2820      \u258c",
+            "\u2590  \u2840     \u258c", "\u2590  \u2820     \u258c",
+            "\u2590   \u2802    \u258c", "\u2590   \u2808    \u258c",
+            "\u2590    \u2802   \u258c", "\u2590    \u2820   \u258c",
+            "\u2590     \u2840  \u258c", "\u2590     \u2820  \u258c",
+            "\u2590      \u2802 \u258c", "\u2590      \u2808 \u258c",
+            "\u2590       \u2802\u258c", "\u2590       \u2820\u258c",
+            "\u2590       \u2840\u258c", "\u2590      \u2820 \u258c",
+            "\u2590      \u2802 \u258c", "\u2590     \u2808  \u258c",
+            "\u2590     \u2802  \u258c", "\u2590    \u2820   \u258c",
+            "\u2590    \u2840   \u258c", "\u2590   \u2820    \u258c",
+            "\u2590   \u2802    \u258c", "\u2590  \u2808     \u258c",
+            "\u2590  \u2802     \u258c", "\u2590 \u2820      \u258c",
+            "\u2590 \u2840      \u258c", "\u2590\u2820       \u258c",
+        ),
+        "two paddles, one braille ball",
+    ),
+    "fistBump": (
+        (
+            "\U0001f91c\u3000\u3000\u3000\u3000\U0001f91b ",
+            "\U0001f91c\u3000\u3000\u3000\u3000\U0001f91b ",
+            "\U0001f91c\u3000\u3000\u3000\u3000\U0001f91b ",
+            "\u3000\U0001f91c\u3000\u3000\U0001f91b\u3000 ",
+            "\u3000\u3000\U0001f91c\U0001f91b\u3000\u3000 ",
+            "\u3000\U0001f91c\u2728\U0001f91b\u3000\u3000 ",
+            "\U0001f91c\u3000\u2728\u3000\U0001f91b\u3000 ",
+        ),
+        "when the work deserves respect",
+    ),
+    "aesthetic": (
+        (
+            "\u25b0\u25b1\u25b1\u25b1\u25b1\u25b1\u25b1",
+            "\u25b0\u25b0\u25b1\u25b1\u25b1\u25b1\u25b1",
+            "\u25b0\u25b0\u25b0\u25b1\u25b1\u25b1\u25b1",
+            "\u25b0\u25b0\u25b0\u25b0\u25b1\u25b1\u25b1",
+            "\u25b0\u25b0\u25b0\u25b0\u25b0\u25b1\u25b1",
+            "\u25b0\u25b0\u25b0\u25b0\u25b0\u25b0\u25b1",
+            "\u25b0\u25b0\u25b0\u25b0\u25b0\u25b0\u25b0",
+            "\u25b1\u25b1\u25b1\u25b1\u25b1\u25b1\u25b1",
+        ),
+        "vaporwave progress vibes",
+    ),
+}
+# fmt: on

code_puppy_core_plugins/puppy_spinner/commands.py

@@ -0,0 +1,116 @@
+"""/spinner -- pick a status-bar spinner style, interactively or by name.
+
+UX:
+  /spinner                  -> interactive picker with live animated preview
+                               (-/+ adjusts speed, i writes a starter
+                               spinners.json, Enter applies)
+  /spinner <name> [seconds] -> apply by name, optionally at a custom speed
+  /spinner init             -> write a starter spinners.json for custom spinners
+
+Custom spinners live in ``spinners.json`` next to ``puppy.cfg``; user
+entries override builtins on name collision. The choice persists in
+``puppy.cfg``, custom speeds save into spinners.json itself, and both
+take effect on the very next tick -- no restart. Edits to spinners.json
+are picked up automatically (mtime watch), so there's no reload command
+to remember.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+
+from code_puppy.messaging import emit_error, emit_info, emit_warning
+
+from . import spinners
+from .picker import interactive_spinner_picker
+
+_INTERACTIVE_TIMEOUT_SECONDS = 300  # 5 min -- generous; user is browsing
+
+
+def help_entries():
+    return [
+        ("spinner", "Pick a status-bar spinner style (interactive: /spinner)"),
+    ]
+
+
+def _run_interactive_picker() -> tuple[str, float | None] | None:
+    """Run the async TUI from a sync command handler (theme-plugin pattern)."""
+    with concurrent.futures.ThreadPoolExecutor() as executor:
+        future = executor.submit(lambda: asyncio.run(interactive_spinner_picker()))
+        return future.result(timeout=_INTERACTIVE_TIMEOUT_SECONDS)
+
+
+def _apply(name: str, interval: float | None = None) -> None:
+    # Match case-insensitively; built-in names use camelCase.
+    catalogue = spinners.get_catalogue()
+    name = next((n for n in catalogue if n.lower() == name.lower()), name)
+    try:
+        spinner = spinners.set_active(name, interval)
+    except KeyError:
+        known = ", ".join(sorted(spinners.get_catalogue()))
+        emit_warning(
+            f"Unknown spinner '{name}'. Try /spinner for the picker, "
+            f"or pick one of: {known}."
+        )
+        return
+    speed_note = " -- speed saved to spinners.json" if interval is not None else ""
+    emit_info(
+        f"Spinner set to '{spinner.name}' "
+        f"({len(spinner.frames)} frames @ {spinner.interval:.2f}s{speed_note}). "
+        f"Sample: {spinner.frames[0].strip()}"
+    )
+
+
+def _init() -> None:
+    try:
+        created = spinners.write_template()
+    except OSError as exc:
+        emit_error(f"Could not write {spinners.USER_SPINNERS_FILE}: {exc}")
+        return
+    if created:
+        emit_info(
+            f"Starter file written: {spinners.USER_SPINNERS_FILE}\n"
+            "Edit it freely -- changes are picked up automatically."
+        )
+    else:
+        emit_info(
+            f"{spinners.USER_SPINNERS_FILE} already exists -- not touching it. "
+            "Edit it directly; changes are picked up automatically."
+        )
+
+
+def handle_spinner(command: str, name: str):
+    """``custom_command`` callback -- owns ``/spinner`` only."""
+    if name != "spinner":
+        return None
+
+    parts = command.split()
+    sub = parts[1].lower() if len(parts) > 1 else ""
+
+    if sub == "":
+        try:
+            chosen = _run_interactive_picker()
+        except Exception as exc:  # pragma: no cover -- defensive UX
+            emit_error(f"Spinner picker failed: {exc}")
+            return True
+        if chosen is None:
+            emit_info("Spinner unchanged.")
+            return True
+        name, interval = chosen
+        _apply(name, interval)
+    elif sub == "init":
+        _init()
+    else:
+        interval = None
+        if len(parts) > 2:
+            try:
+                interval = float(parts[2])
+            except ValueError:
+                emit_warning(
+                    f"'{parts[2]}' is not a number of seconds. "
+                    "Usage: /spinner <name> [seconds]"
+                )
+                return True
+        _apply(sub, interval)
+    return True

code_puppy_core_plugins/puppy_spinner/picker.py

@@ -0,0 +1,379 @@
+"""Interactive spinner picker TUI.
+
+Same full-screen prompt_toolkit pattern as the theme plugin's picker,
+but with a preview pane that actually *animates*: a background asyncio
+task invalidates the app ~20x/sec, and the preview control derives the
+current frame from wall-clock time, so every spinner runs at its own
+configured interval.
+
+Navigation follows the plugins-menu convention (same split-pane shape,
+same muscle memory): ``j``/``k`` + arrows move the selection (clamped,
+no wraparound), ``pageup``/``pagedown`` page through the list via the
+shared pagination helpers, ``g``/``G``/``home``/``end`` jump to the
+first/last entry, ``enter`` applies, and ``q``/``esc``/``ctrl-c`` bail.
+``i`` writes the starter spinners.json without leaving; the animator
+task also watches the file's mtime, so external edits reload the menu
+live while the picker is open.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import time
+from typing import List, Optional, Tuple
+
+from prompt_toolkit import Application
+from prompt_toolkit.formatted_text import FormattedText
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.layout import Layout, VSplit, Window
+from prompt_toolkit.layout.controls import FormattedTextControl
+from prompt_toolkit.widgets import Frame
+
+from code_puppy.command_line.pagination import (
+    ensure_visible_page,
+    get_page_bounds,
+    get_page_for_index,
+    get_total_pages,
+)
+
+from . import spinners as sp
+from code_puppy.callbacks import on_prompt_toolkit_style
+
+#: Preview invalidation cadence, pinned to MIN_INTERVAL so slowest spinners run
+#: at their true speed.
+_REFRESH_INTERVAL_S = sp.MIN_INTERVAL
+PAGE_SIZE = 20  # one line per entry, same as the plugins menu
+#: Speed-key grid step; matching the clamp floor keeps 0.02..1.0 on-grid.
+_SPEED_STEP_S = 0.02
+
+
+def _step_interval(current: float, delta: float) -> float:
+    """One speed-key step from *current*: snap to the step grid, then clamp.
+
+    Snapping matters at the edges: clamping alone strands you off-grid
+    (0.05 -> floor 0.02 -> 0.07 -> 0.12 ...). Rounding to the nearest
+    multiple of the step first means the floor is just a stop -- the
+    next nudge up lands back on 0.05. Off-grid starting values (from a
+    spinners.json tweak) get folded onto the grid the same way.
+    """
+    stepped = round((current + delta) / _SPEED_STEP_S) * _SPEED_STEP_S
+    return sp.clamp_interval(stepped)
+
+
+def _format_menu(
+    entries: List[sp.Spinner], selected: int, page: int, active: str
+) -> FormattedText:
+    """Left-hand menu, styled to match the plugins menu's list pane.
+
+    One line per entry: ``" > "`` marks the selection (bold), a green
+    ``*`` glyph marks the active spinner (the plugins menu's ``+``/``x``
+    slot), names only -- descriptions live in the preview pane, exactly
+    like plugin descriptions live in the detail pane.
+    """
+    total_pages = get_total_pages(len(entries), PAGE_SIZE)
+    start, end = get_page_bounds(page, len(entries), PAGE_SIZE)
+
+    lines: list[tuple[str, str]] = [
+        ("class:tui.header", " Spinners"),
+        ("", "\n\n"),
+    ]
+    for i in range(start, end):
+        spinner = entries[i]
+        is_selected = i == selected
+        icon = "*" if spinner.name == active else " "
+        prefix = " > " if is_selected else "   "
+
+        if is_selected:
+            lines.append(("class:tui.selected", prefix))
+            lines.append(("class:tui.selected", icon))
+            lines.append(("class:tui.selected", f" {spinner.name}"))
+        else:
+            lines.append(("class:tui.body", prefix))
+            lines.append(("class:tui.success", icon))
+            lines.append(("class:tui.muted", f" {spinner.name}"))
+        lines.append(("", "\n"))
+
+    lines.append(("", "\n"))
+    lines.append(("class:tui.muted", f" Page {page + 1}/{total_pages}"))
+    lines.append(("", "\n"))
+
+    _render_hints(lines)
+    return FormattedText(lines)
+
+
+#: Hint rows; ``_render_hints`` pads keys to keep action columns aligned.
+_HINTS = [
+    ("class:tui.help-key", "up/down or j/k", "Navigate"),
+    ("class:tui.help-key", "PgUp/PgDn", "Page"),
+    ("class:tui.help-key", "g / G", "First / Last"),
+    ("class:tui.help-key", "-/+ or \u2190/\u2192", "Slower / Faster"),
+    ("class:tui.help-key", "i", "Init spinners.json"),
+    ("class:tui.success", "Enter", "Apply"),
+    ("class:tui.error", "q / Esc", "Exit"),
+]
+
+
+def _render_hints(lines: list[tuple[str, str]]) -> None:
+    """The plugins menu's hint block, with a speed row where their
+    detail-scroll row sits. The key column is computed, not hand-padded.
+    """
+    key_col = max(len(keys) for _, keys, _ in _HINTS) + 1
+    lines.append(("", "\n"))
+    for i, (style, keys, label) in enumerate(_HINTS):
+        lines.append((style, f"  {keys.ljust(key_col)}"))
+        lines.append(
+            ("class:tui.help", label if i == len(_HINTS) - 1 else f"{label}\n")
+        )
+
+
+def _format_preview(
+    spinner: sp.Spinner,
+    started_at: float,
+    interval: Optional[float] = None,
+    notice: str = "",
+) -> FormattedText:
+    """Right-hand pane, styled like the plugins menu's detail pane.
+
+    *interval* is the speed the user dialed with the speed keys; None
+    means the spinner's own speed (the usual case). *notice* is a
+    one-line status message (e.g. the outcome of pressing ``i``).
+    """
+    effective = interval if interval is not None else spinner.interval
+    elapsed = time.monotonic() - started_at
+    frame = spinner.frames[int(elapsed / effective) % len(spinner.frames)]
+    lines: list[tuple[str, str]] = [
+        ("class:tui.title", " LIVE PREVIEW"),
+        ("", "\n\n"),
+        ("class:tui.label", f"  {spinner.name}"),
+        ("", "\n\n"),
+    ]
+    if spinner.description:
+        lines.append(("", f"  {spinner.description}"))
+        lines.append(("", "\n\n"))
+    lines.extend(
+        [
+            ("class:tui.label", f"  {frame}"),
+            ("", "\n\n"),
+            ("class:tui.label", "  Source: "),
+            ("class:tui.body", spinner.source),
+            ("", "\n"),
+            ("class:tui.label", "  Frames: "),
+            ("class:tui.body", str(len(spinner.frames))),
+            ("", "\n"),
+            ("class:tui.label", "  Interval: "),
+            ("class:tui.body", f"{effective:.2f}s"),
+            (
+                "class:tui.warning",
+                "  (custom -- Enter saves it)" if interval is not None else "",
+            ),
+            ("", "\n\n"),
+            ("class:tui.label", "  Custom spinners:"),
+            ("", "\n"),
+            ("class:tui.muted", f"    {sp.USER_SPINNERS_FILE}"),
+            ("", "\n"),
+            ("class:tui.muted", "    (press i to write a starter file)"),
+            ("", "\n"),
+        ]
+    )
+    if notice:
+        lines.append(("", "\n"))
+        lines.append(("class:tui.warning", f"  {notice}"))
+        lines.append(("", "\n"))
+    return FormattedText(lines)
+
+
+async def interactive_spinner_picker() -> Optional[Tuple[str, Optional[float]]]:
+    """Show the full-screen spinner picker.
+
+    Returns:
+        ``(name, interval)`` -- *interval* is the dialed custom speed or
+        None for the spinner's own speed -- or ``None`` if cancelled.
+    """
+    from code_puppy.tools.command_runner import set_awaiting_user_input
+
+    entries = list(sp.get_catalogue().values())
+    active = sp.get_active_spinner().name
+    selected = [next((i for i, s in enumerate(entries) if s.name == active), 0)]
+    page = [get_page_for_index(selected[0], PAGE_SIZE)]
+    custom_interval: list[Optional[float]] = [None]
+    notice = [""]
+    result: list[Optional[Tuple[str, Optional[float]]]] = [None]
+    started_at = time.monotonic()
+
+    set_awaiting_user_input(True)
+    sys.stdout.write("\033[?1049h\033[2J\033[H")
+    sys.stdout.flush()
+    await asyncio.sleep(0.05)
+
+    def _set_selection(new_idx: int) -> None:
+        """Clamp selection and keep its page visible (plugins-menu contract).
+
+        Moving resets the dialed speed -- each entry previews at its own
+        speed until you nudge it.
+        """
+        selected[0] = max(0, min(new_idx, len(entries) - 1))
+        page[0] = ensure_visible_page(selected[0], page[0], len(entries), PAGE_SIZE)
+        custom_interval[0] = None
+
+    def _nudge_speed(delta: float) -> None:
+        current = (
+            custom_interval[0]
+            if custom_interval[0] is not None
+            else entries[selected[0]].interval
+        )
+        custom_interval[0] = _step_interval(current, delta)
+
+    def _refresh_entries() -> None:
+        """Re-read the catalogue in place, keeping the selection pinned by
+        name. Shared by the ``i`` key and the live file watcher."""
+        current_name = entries[selected[0]].name
+        entries[:] = list(sp.get_catalogue().values())
+        _set_selection(
+            next((i for i, s in enumerate(entries) if s.name == current_name), 0)
+        )
+
+    def _change_page(delta: int) -> None:
+        """Move the page by *delta* (clamped) and jump selection to its head."""
+        total_pages = get_total_pages(len(entries), PAGE_SIZE)
+        new_page = max(0, min(page[0] + delta, total_pages - 1))
+        if new_page == page[0]:
+            return
+        page[0] = new_page
+        _set_selection(new_page * PAGE_SIZE)
+
+    kb = KeyBindings()
+
+    # -- Selection (j = up, k = down -- plugins-menu convention) ------------
+    @kb.add("up")
+    @kb.add("c-p")
+    @kb.add("j")
+    def _(event):
+        _set_selection(selected[0] - 1)
+        event.app.invalidate()
+
+    @kb.add("down")
+    @kb.add("c-n")
+    @kb.add("k")
+    def _(event):
+        _set_selection(selected[0] + 1)
+        event.app.invalidate()
+
+    # -- Page through the list ----------------------------------------------
+    @kb.add("pageup")
+    def _(event):
+        _change_page(-1)
+        event.app.invalidate()
+
+    @kb.add("pagedown")
+    def _(event):
+        _change_page(+1)
+        event.app.invalidate()
+
+    # -- Jump to first / last -------------------------------------------------
+    @kb.add("home")
+    @kb.add("g")
+    def _(event):
+        _set_selection(0)
+        event.app.invalidate()
+
+    @kb.add("end")
+    @kb.add("G")
+    def _(event):
+        _set_selection(len(entries) - 1)
+        event.app.invalidate()
+
+    # -- Speed (left/- slower, right/+ faster: interval moves inversely) ----
+    @kb.add("left")
+    @kb.add("-")
+    def _(event):
+        _nudge_speed(+_SPEED_STEP_S)
+        event.app.invalidate()
+
+    @kb.add("right")
+    @kb.add("+")
+    @kb.add("=")  # unshifted + on most layouts
+    def _(event):
+        _nudge_speed(-_SPEED_STEP_S)
+        event.app.invalidate()
+
+    # -- Init the user spinners file (no need to leave the menu) -----------
+    @kb.add("i")
+    def _(event):
+        try:
+            created = sp.write_template()
+            notice[0] = (
+                "Starter file written -- edit it freely, changes apply live."
+                if created
+                else "spinners.json already exists -- edit it directly."
+            )
+        except OSError as exc:
+            notice[0] = f"Could not write starter file: {exc}"
+        _refresh_entries()
+        event.app.invalidate()
+
+    # -- Actions / exit --------------------------------------------------------
+    @kb.add("enter")
+    def _(event):
+        result[0] = (entries[selected[0]].name, custom_interval[0])
+        event.app.exit()
+
+    @kb.add("q")
+    @kb.add("escape")
+    @kb.add("c-c")
+    def _(event):
+        result[0] = None
+        event.app.exit()
+
+    left = Window(
+        content=FormattedTextControl(
+            lambda: _format_menu(entries, selected[0], page[0], active)
+        ),
+        width=36,  # widest hint row is 35 cells; don't guillotine the json
+    )
+    right = Window(
+        content=FormattedTextControl(
+            lambda: _format_preview(
+                entries[selected[0]], started_at, custom_interval[0], notice[0]
+            )
+        ),
+    )
+
+    layout = Layout(
+        VSplit([Frame(left, title="Spinners"), Frame(right, title="Live Preview")])
+    )
+    app = Application(
+        layout=layout,
+        key_bindings=kb,
+        full_screen=False,
+        mouse_support=False,
+        style=on_prompt_toolkit_style(),
+    )
+
+    async def _animate() -> None:
+        """Poke the app awake so the preview frame advances -- and watch
+        spinners.json so external edits reload the menu while it's open
+        (the same mtime signal the tick loop uses).
+        """
+        file_stamp = sp.user_file_stamp()
+        try:
+            while True:
+                await asyncio.sleep(_REFRESH_INTERVAL_S)
+                stamp = sp.user_file_stamp()
+                if stamp != file_stamp:
+                    file_stamp = stamp
+                    _refresh_entries()
+                app.invalidate()
+        except asyncio.CancelledError:
+            pass
+
+    animator = asyncio.get_running_loop().create_task(_animate())
+    try:
+        await app.run_async()
+    finally:
+        animator.cancel()
+        set_awaiting_user_input(False)
+        sys.stdout.write("\033[?1049l")
+        sys.stdout.flush()
+
+    return result[0]