vimniscient 0.2.0__py3-none-any.whl

vimniscient/cards/zathura.yaml

@@ -0,0 +1,32 @@
+deck: zathura
+title: Zathura (PDF)
+requires: zathura
+style: keys
+case_sensitive: true
+# Defaults from zathura(1); ~/.config/zathura/zathurarc doesn't change any keys.
+cards:
+  - {prompt: Next page, answer: [J, <PageDown>]}
+  - {prompt: Previous page, answer: [K, <PageUp>]}
+  - {prompt: Half a page down, answer: [<C-d>]}
+  - {prompt: Go to the first page, answer: [gg]}
+  - {prompt: Go to the last page, answer: [G]}
+  - {prompt: Go to page 12, answer: [12G]}
+  - {prompt: Search the text, answer: [/]}
+  - {prompt: Fit the page width, answer: [s]}
+  - {prompt: Fit the whole page, answer: [a]}
+  - {prompt: Zoom in, answer: ['+', zI]}
+  - {prompt: Zoom out, answer: ['-', zO]}
+  - {prompt: Zoom back to the original size, answer: ['=', z0]}
+  - {prompt: Dark mode (recolor), answer: [<C-r>]}
+  - {prompt: Show the table of contents, answer: [<Tab>]}
+  - {prompt: Toggle two pages side by side, answer: [d]}
+  - {prompt: Follow a link with the keyboard, answer: [f]}
+  - {prompt: Rotate the page, answer: [r]}
+  - {prompt: Reload the document, answer: [R]}
+  - {prompt: Jump back after following a link, answer: [<C-o>]}
+  - {prompt: Set quickmark a, answer: [ma]}
+  - {prompt: Go to quickmark a, answer: ["'a"]}
+  - {prompt: Presentation mode, answer: [<F5>]}
+  - {prompt: Fullscreen, answer: [<F11>]}
+  - {prompt: Toggle the status bar, answer: [<C-n>]}
+  - {prompt: Open another document, answer: [o]}

vimniscient/cards.py

@@ -0,0 +1,200 @@
+"""Flashcards: static decks from `cards/*.yaml` plus decks read live from the
+user's setup (Omarchy, tmux and LazyVim keybindings)."""
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from importlib import resources
+from pathlib import Path
+
+import yaml
+
+from vimniscient.answer import pretty_keys
+
+NVIM_DATA = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local/share")) / "nvim"
+CACHE_DIR = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "vimniscient"
+NVIM_CONFIG = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "nvim"
+
+# New cards are introduced round-robin in this order.
+DECK_ORDER = ["habits", "vim", "lazyvim", "omarchy", "tmux", "shell", "foot", "zathura"]
+
+
+@dataclass
+class Card:
+    deck: str
+    id: str
+    prompt: str
+    answers: list[str]
+    style: str  # keys | combo
+    case_sensitive: bool
+    week: int = 0
+    day: int = 0  # the lesson (in `week`) that teaches it; 0 for none
+    note: str = ""
+    order: int = 0  # position within the deck for introducing new cards
+
+    @property
+    def shown(self) -> str:
+        return pretty_keys(self.answers[0])
+
+    @property
+    def also(self) -> list[str]:
+        return [pretty_keys(a) for a in self.answers[1:]]
+
+
+@dataclass
+class Deck:
+    id: str
+    title: str
+    cards: list[Card] = field(default_factory=list)
+
+
+def has_plugin(name: str) -> bool:
+    """A Neovim plugin installed through lazy.nvim."""
+    return (NVIM_DATA / "lazy" / name).is_dir()
+
+
+def has_lazyvim() -> bool:
+    """LazyVim's lessons and cards need it."""
+    return has_plugin("LazyVim")
+
+
+def _static_decks() -> dict[str, Deck]:
+    decks = {}
+    for f in (resources.files("vimniscient") / "cards").iterdir():
+        if not f.name.endswith(".yaml"):
+            continue
+        data = yaml.safe_load(f.read_text(encoding="utf-8"))
+        # a deck about a program only shows up when that program is installed
+        if data.get("requires") == "lazyvim" and not has_lazyvim():
+            continue
+        if data.get("requires") not in (None, "lazyvim") and not shutil.which(data["requires"]):
+            continue
+        deck = Deck(data["deck"], data["title"])
+        for i, c in enumerate(data["cards"]):
+            deck.cards.append(
+                Card(
+                    deck=deck.id,
+                    id=f"{deck.id}:{c['prompt']}",
+                    prompt=c["prompt"],
+                    answers=[str(a) for a in c["answer"]],
+                    style=data.get("style", "keys"),
+                    case_sensitive=data.get("case_sensitive", True),
+                    week=c.get("week", 0),
+                    day=c.get("day", 0),
+                    note=c.get("note", data.get("note", "")),
+                    order=i,
+                )
+            )
+        decks[deck.id] = deck
+    return decks
+
+
+def _run(cmd: list[str]) -> str:
+    try:
+        return subprocess.run(cmd, capture_output=True, text=True, timeout=20).stdout
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+
+
+def _arrow_list(deck_id: str, text: str, case_sensitive: bool) -> list[Card]:
+    """Cards from `KEYS → description` lines (the Omarchy keybinding menus)."""
+    by_desc: dict[str, list[str]] = {}
+    for line in text.splitlines():
+        if "→" not in line:
+            continue
+        keys, desc = (s.strip() for s in line.split("→", 1))
+        if not keys or not desc or re.search(r"MOUSE|SCROLL|SWITCH:|XF86", keys, re.I):
+            continue
+        by_desc.setdefault(desc, []).append(keys)
+    cards = []
+    for i, (desc, keys) in enumerate(by_desc.items()):
+        # "Switch to workspace 1..10" is one thing to learn: keep the 1.
+        m = re.fullmatch(r"(.*\D)(\d+)", desc)
+        if m and m.group(2) != "1" and f"{m.group(1)}1" in by_desc:
+            continue
+        if keys == ["PREFIX"]:  # tmux: "PREFIX → CTRL + SPACE / CTRL + B"
+            desc, keys = "The tmux prefix", [k.strip() for k in desc.split("/")]
+        cards.append(
+            Card(deck_id, f"{deck_id}:{desc}", desc, keys, "combo", case_sensitive, order=i)
+        )
+    return cards
+
+
+def omarchy_cards() -> list[Card]:
+    return _arrow_list("omarchy", _run(["omarchy", "menu", "keybindings", "--print"]), False)
+
+
+def tmux_cards() -> list[Card]:
+    return _arrow_list("tmux", _run(["omarchy-menu-tmux-keybindings", "--print"]), True)
+
+
+def _nvim_signature() -> str:
+    newest = 0.0
+    for root, _, files in os.walk(NVIM_CONFIG):
+        for name in files:
+            newest = max(newest, os.path.getmtime(os.path.join(root, name)))
+    return str(newest)
+
+
+def nvim_keymaps() -> list[dict]:
+    """Every described keymap in the user's Neovim, cached until the config changes."""
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    cache = CACHE_DIR / "nvim-keymaps.json"
+    signature = _nvim_signature()
+    if cache.exists():
+        data = json.loads(cache.read_text())
+        if data.get("signature") == signature:
+            return data["maps"]
+    out = CACHE_DIR / "nvim-keymaps.tmp.json"
+    script = resources.files("vimniscient") / "nvim" / "keymaps.lua"
+    with resources.as_file(script) as script_path:
+        try:
+            subprocess.run(
+                ["nvim", "--headless", "-i", "NONE", "-n", "-S", str(script_path)],
+                env=os.environ | {"VIMNISCIENT_KEYMAPS": str(out)},
+                capture_output=True,
+                timeout=60,
+                cwd=CACHE_DIR,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return []
+    if not out.exists():
+        return []
+    maps = json.loads(out.read_text())
+    out.unlink()
+    cache.write_text(json.dumps({"signature": signature, "maps": maps}))
+    return maps
+
+
+def lazyvim_extra_cards(core: list[Card]) -> list[Card]:
+    """The `from_config` keymaps of cards/lazyvim.yaml, as named in the user's config."""
+    data = yaml.safe_load((resources.files("vimniscient") / "cards" / "lazyvim.yaml").read_text(encoding="utf-8"))
+    wanted = [pretty_keys(k) for k in data.get("from_config", [])]
+    known = {a for card in core for a in card.answers}
+    by_lhs = {
+        pretty_keys(m["lhs"]): m["desc"]
+        for m in nvim_keymaps()
+        if m["mode"] == "n" and not m["desc"].startswith("+")
+    }
+    start = len(core)
+    return [
+        Card("lazyvim", f"lazyvim:{by_lhs[lhs]}", by_lhs[lhs], [lhs], "keys", True, order=start + i)
+        for i, lhs in enumerate(lhs for lhs in wanted if lhs in by_lhs and lhs not in known)
+    ]
+
+
+def load_decks(live: bool = True) -> dict[str, Deck]:
+    decks = _static_decks()
+    if live:
+        for deck in (Deck("omarchy", "Omarchy", omarchy_cards()), Deck("tmux", "tmux", tmux_cards())):
+            if deck.cards:
+                decks[deck.id] = deck
+        if "lazyvim" in decks:
+            decks["lazyvim"].cards += lazyvim_extra_cards(decks["lazyvim"].cards)
+        from vimniscient.habits import habit_deck
+
+        decks["habits"] = habit_deck()
+    return {d: decks[d] for d in DECK_ORDER if d in decks} | {d: v for d, v in decks.items() if d not in DECK_ORDER}

vimniscient/cli.py

@@ -0,0 +1,98 @@
+"""`vimniscient` opens the menu; `vimniscient list` / `vimniscient run <id>` skip it."""
+
+import argparse
+
+from vimniscient.lessons import load_lessons
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="vimniscient", description="Absolute vim: a daily trainer.")
+    sub = parser.add_subparsers(dest="command")
+    sub.add_parser("list", help="list the lessons")
+    endless_cmd = sub.add_parser("endless", help="endless mode without the menu")
+    endless_cmd.add_argument("--seed", help="the same tasks every time (for testing)")
+    run = sub.add_parser("run", help="run one lesson without the menu")
+    run.add_argument("lesson", help="lesson id, e.g. w1d1-words (see `list`)")
+    remind = sub.add_parser("remind", help="notify about today's practice if any is left (for timers and hooks)")
+    remind.add_argument("--login", action="store_true", help="you just started using the computer")
+    remind.add_argument("--check", action="store_true", help="a follow-up reminder firing")
+    budget = sub.add_parser("minutes", help="how long today's routine is meant to take (15 by default)")
+    budget.add_argument("minutes", type=int, nargs="?", help="set it; leave it out to see it")
+    setup = sub.add_parser("reminders", help="daily practice reminders through Omarchy")
+    setup.add_argument("action", choices=["install", "uninstall", "status"], nargs="?", default="status")
+    args = parser.parse_args()
+
+    if args.command is None:
+        from vimniscient.app import VimniscientApp
+        from vimniscient.session import mouse_wheel
+
+        try:
+            VimniscientApp().run(mouse=False)  # keyboard only: nothing in it reacts to clicks or the wheel
+        finally:
+            mouse_wheel(True)
+        return
+
+    if args.command == "remind":
+        from vimniscient import reminders
+
+        print(reminders.remind("check" if args.check else "login"))
+        return
+    if args.command == "minutes":
+        from vimniscient import settings
+
+        if args.minutes is not None:
+            if args.minutes < 1:
+                parser.error("at least one minute")
+            settings.set_minutes(args.minutes)
+        print(f"Today's routine takes about {settings.minutes()} minutes. ({settings.CONFIG})")
+        return
+    if args.command == "reminders":
+        from vimniscient import reminders
+
+        if args.action == "install":
+            for path in reminders.install():
+                print(f"wrote {path}")
+            print(f"Reminders on: at {reminders.MORNING} or when you start using the computer, then every "
+                  f"{reminders.EVERY // 60} hours until {reminders.DAY_END:%H:%M} while practice is left.")
+        elif args.action == "uninstall":
+            reminders.uninstall()
+            print("Reminders off.")
+        print(reminders.status())
+        return
+
+    lessons = load_lessons()
+    if args.command == "list":
+        for lesson in lessons:
+            print(f"{lesson.id:28} {lesson.label}: {lesson.title} ({len(lesson.tasks)} tasks)")
+        return
+
+    from vimniscient.progress import Progress
+    from vimniscient.session import run_endless, run_lesson
+
+    if args.command == "endless":
+        from vimniscient import endless
+        from vimniscient.cards import has_lazyvim
+
+        progress = Progress()
+        start = progress.endless_start(endless.RESTART_BELOW)
+        rungs = endless.ladder([lesson for lesson in lessons if not lesson.lazyvim or has_lazyvim()], start, seed=args.seed)
+        results = run_endless({t.item_id: t for t, _ in rungs}, [(t.item_id, v) for t, v in rungs],
+                              start, endless.RAMP, endless.GAP)
+        run = endless.summary(results, start)
+        progress.record_endless(results, run)
+        for r in results:
+            print(f"{r.task.phase:6} {r.level:4} {r.status:8} {r.count:>3}/{r.budget or '-'} keys  {r.task.goal}")
+        print(f"Level {run['start']} -> {run['level']}: {run['missed']} missed, {run['fixed']} recalled afterwards")
+        return
+
+    lesson = next((lesson for lesson in lessons if lesson.id == args.lesson), None)
+    if lesson is None:
+        parser.error(f"no lesson {args.lesson!r}; try `vimniscient list`")
+    from dataclasses import replace
+
+    from vimniscient.lessons import two_rounds
+
+    results = run_lesson(replace(lesson, tasks=two_rounds(lesson)), retry=True)
+    Progress().record(results)
+    for i, r in enumerate(results, 1):
+        print(f"{i:2}. {r.task.phase:6} {r.status:8} {r.count if r.status == 'solved' else '-':>3} keys (ref {r.task.ref})  {r.task.goal}")

vimniscient/drills/omarchy.yaml

@@ -0,0 +1,88 @@
+# Live Omarchy drills: the trainer watches Hyprland's event socket and ticks a
+# step off when it really happened.
+#
+# A step matches an event by name and arguments (the part after `>>`, split on
+# commas). Argument patterns:
+#   $drill  the drill window's address     $home  the trainer's workspace
+#   $away   workspace 9 (8 if you're on 9)
+#   $new    any other window; the first match is remembered for later steps
+#   !drill  any window but the drill window
+#   *       anything                        other text must match exactly
+# `active: $drill` also requires the drill window to have focus (for events
+# like `fullscreen` that don't name a window).
+# `bindings` are descriptions from `omarchy menu keybindings --print`; the hint
+# shows their keys live.
+drills:
+  - id: focus
+    title: Focus the drill window
+    bindings: [Focus on left window, Focus on right window, Focus on next window]
+    prompt: Without the mouse, move the focus off the drill window, then back onto it.
+    steps:
+      - {event: activewindowv2, args: ["!drill"], done: focus moved away}
+      - {event: activewindowv2, args: [$drill], done: drill window focused}
+
+  - id: float
+    title: Float and tile
+    bindings: [Toggle window floating/tiling]
+    prompt: Make the drill window float, then tile it again.
+    steps:
+      - {event: changefloatingmode, args: [$drill, "1"], done: floating}
+      - {event: changefloatingmode, args: [$drill, "0"], done: tiled again}
+
+  - id: fullscreen
+    title: Full screen
+    bindings: [Full screen]
+    prompt: Make the drill window full screen, then leave full screen.
+    steps:
+      - {event: fullscreen, args: ["1"], active: $drill, done: full screen}
+      - {event: fullscreen, args: ["0"], active: $drill, done: back to normal}
+
+  - id: full-width
+    title: Full width
+    bindings: [Full width]
+    prompt: Give the drill window the full width (not full screen), then undo it.
+    steps:
+      - {event: fullscreen, args: ["1"], active: $drill, done: full width}
+      - {event: fullscreen, args: ["0"], active: $drill, done: back to normal}
+
+  - id: pop
+    title: Pop a window out
+    bindings: [Pop window out (float & pin)]
+    prompt: Pop the drill window out (float and pin it), then put it back.
+    steps:
+      - {event: pin, args: [$drill, "1"], done: popped out}
+      - {event: pin, args: [$drill, "0"], done: back in place}
+
+  - id: workspace-visit
+    title: Visit a workspace and come back
+    bindings: [Switch to workspace 1, Former workspace]
+    prompt: Go to workspace {away}, then come straight back here (workspace {home}). There's a key for "back".
+    steps:
+      - {event: workspacev2, args: [$away, "*"], done: "on workspace {away}"}
+      - {event: workspacev2, args: [$home, "*"], done: "back on workspace {home}"}
+
+  - id: workspace-move
+    title: Send a window away and fetch it
+    bindings: [Move window silently to workspace 1, Switch to workspace 1, Move window to workspace 1]
+    prompt: >-
+      Send the drill window to workspace {away} without following it. Then go to
+      workspace {away} and take it back to workspace {home} with you.
+    steps:
+      - {event: movewindowv2, args: [$drill, $away, "*"], done: "sent to workspace {away}"}
+      - {event: workspacev2, args: [$away, "*"], done: "on workspace {away}"}
+      - {event: movewindowv2, args: [$drill, $home, "*"], done: brought back}
+
+  - id: terminal
+    title: Open and close a terminal
+    bindings: [Terminal, Close window]
+    prompt: Open a new terminal, then close it again with the keyboard.
+    steps:
+      - {event: openwindow, args: [$new, "*", "*", "*"], done: terminal open}
+      - {event: closewindow, args: [$new], done: closed}
+
+  - id: close
+    title: Close a window
+    bindings: [Close window]
+    prompt: Close the drill window with the keyboard. (A new one opens for the next drill.)
+    steps:
+      - {event: closewindow, args: [$drill], done: closed}

vimniscient/drills.py

@@ -0,0 +1,198 @@
+"""Live Omarchy drills, checked against Hyprland's event socket (socket2).
+
+The matching (`DrillRun.feed`) is plain and testable; `Hyprland` holds the
+parts that touch the desktop: the drill window and the sockets.
+"""
+
+import asyncio
+import json
+import os
+import subprocess
+import time
+from dataclasses import dataclass, field
+from importlib import resources
+
+import yaml
+
+DRILL_CLASS = "vimniscient-drill"
+DRILL_TITLE = "Vimniscient drill"
+
+
+@dataclass
+class Step:
+    event: str
+    args: list[str]
+    done: str
+    active: str | None = None
+
+
+@dataclass
+class Drill:
+    id: str
+    title: str
+    prompt: str
+    bindings: list[str]
+    steps: list[Step]
+
+    @property
+    def item_id(self) -> str:
+        return f"drill:{self.id}"
+
+
+def load_drills() -> list[Drill]:
+    data = yaml.safe_load((resources.files("vimniscient") / "drills" / "omarchy.yaml").read_text(encoding="utf-8"))
+    return [
+        Drill(
+            id=d["id"],
+            title=d["title"],
+            prompt=d["prompt"],
+            bindings=d.get("bindings", []),
+            steps=[Step(s["event"], [str(a) for a in s["args"]], s["done"], s.get("active")) for s in d["steps"]],
+        )
+        for d in data["drills"]
+    ]
+
+
+@dataclass
+class DrillRun:
+    """Walks one drill's steps as events come in."""
+
+    drill: Drill
+    drill_addr: str  # without 0x, as the events write it
+    home: str  # workspace id
+    step: int = 0
+    active: str = ""  # address of the focused window
+    new: str | None = None
+    started: float = field(default_factory=time.monotonic)
+
+    @property
+    def away(self) -> str:
+        return "8" if self.home == "9" else "9"
+
+    def text(self, template: str) -> str:
+        return template.replace("{home}", self.home).replace("{away}", self.away)
+
+    @property
+    def finished(self) -> bool:
+        return self.step >= len(self.drill.steps)
+
+    def _arg_ok(self, pattern: str, value: str) -> bool:
+        if pattern == "*":
+            return True
+        if pattern == "$drill":
+            return value == self.drill_addr
+        if pattern == "$home":
+            return value == self.home
+        if pattern == "$away":
+            return value == self.away
+        if pattern == "!drill":
+            return bool(value) and value != self.drill_addr
+        if pattern == "$new":
+            if self.new is None:
+                if value and value != self.drill_addr:
+                    self.new = value
+                    return True
+                return False
+            return value == self.new
+        return value == pattern
+
+    def feed(self, line: str) -> Step | None:
+        """Take one `event>>data` line; returns the step it completed, if any."""
+        name, _, data = line.partition(">>")
+        if name == "activewindowv2":
+            self.active = data.removeprefix("0x")
+        if self.finished:
+            return None
+        step = self.drill.steps[self.step]
+        if name != step.event:
+            return None
+        args = data.split(",", len(step.args) - 1) if step.args else []
+        if len(args) != len(step.args):
+            return None
+        if step.active == "$drill" and self.active != self.drill_addr:
+            return None
+        new_before = self.new
+        if not all(self._arg_ok(p, v) for p, v in zip(step.args, args)):
+            self.new = new_before
+            return None
+        self.step += 1
+        return step
+
+
+def grade(seconds: float, hinted: bool, skipped: bool) -> int:
+    from vimniscient import srs
+
+    if skipped:
+        return srs.AGAIN
+    if hinted:
+        return srs.HARD
+    return srs.EASY if seconds <= 10 else srs.GOOD if seconds <= 30 else srs.HARD
+
+
+class Hyprland:
+    """The live desktop: the drill window and the event stream."""
+
+    def __init__(self) -> None:
+        sig = os.environ.get("HYPRLAND_INSTANCE_SIGNATURE")
+        runtime = os.environ.get("XDG_RUNTIME_DIR", "")
+        self.socket2 = os.path.join(runtime, "hypr", sig, ".socket2.sock") if sig else ""
+        self.drill_window: subprocess.Popen | None = None
+
+    @property
+    def available(self) -> bool:
+        return bool(self.socket2) and os.path.exists(self.socket2)
+
+    def _json(self, what: str):
+        out = subprocess.run(["hyprctl", what, "-j"], capture_output=True, text=True, timeout=5).stdout
+        return json.loads(out or "null")
+
+    def home(self) -> str:
+        return str(self._json("activeworkspace")["id"])
+
+    def drill_address(self) -> str | None:
+        for client in self._json("clients") or []:
+            if client.get("class") == DRILL_CLASS:
+                return client["address"].removeprefix("0x")
+        return None
+
+    def ensure_drill_window(self) -> str | None:
+        """Open the drill window if it isn't there; returns its address."""
+        addr = self.drill_address()
+        if addr:
+            return addr
+        text = "This is the drill window.\\nThe drills happen to it, so your own windows are left alone."
+        self.drill_window = subprocess.Popen(
+            [
+                "xdg-terminal-exec", f"--app-id={DRILL_CLASS}", f"--title={DRILL_TITLE}",
+                # it closes itself once the trainer is gone, even if that crashed
+                "-e", "sh", "-c", f'printf "\\n  {text}\\n"; while kill -0 {os.getpid()} 2>/dev/null; do sleep 2; done',
+            ],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        for _ in range(50):
+            time.sleep(0.1)
+            addr = self.drill_address()
+            if addr:
+                return addr
+        return None
+
+    def close_drill_window(self) -> None:
+        addr = self.drill_address()
+        if addr:
+            subprocess.run(
+                ["hyprctl", "dispatch", f'hl.dsp.window.close({{ window = "address:0x{addr}" }})'],
+                capture_output=True,
+                timeout=5,
+            )
+        if self.drill_window and self.drill_window.poll() is None:
+            self.drill_window.terminate()
+
+    async def events(self):
+        """Yield `event>>data` lines from socket2 forever."""
+        reader, writer = await asyncio.open_unix_connection(self.socket2)
+        try:
+            while line := await reader.readline():
+                yield line.decode(errors="replace").rstrip("\n")
+        finally:
+            writer.close()

vimniscient/endless.py

@@ -0,0 +1,60 @@
+"""Endless mode: tasks from every lesson, one after another, getting harder.
+
+Each task you solve climbs a level. Two things make the climb harder:
+- the mix: it starts with the first lesson and takes in the next one every
+  LEVELS_PER_LESSON levels, half the time picking from the newest lesson;
+- the key budget: about twice the reference at level 1, shrinking to exactly
+  the reference by level RAMP (the runner works it out, see runner.lua).
+
+Going over the budget, :Skip, or asking for the answer counts as a miss. A
+miss shows the answer, gives the task again with the keys shown (Learn), and
+GAP tasks later brings it back on another text, from memory (Recall).
+"""
+
+import math
+import random
+from collections import deque
+
+from vimniscient.lessons import Lesson, Task
+
+LEVELS_PER_LESSON = 4
+RAMP = 200
+GAP = 2
+RUNGS = 1000  # more than anyone climbs in a sitting; the runner wraps around after
+RESTART_BELOW = 10  # a new run starts this many levels below where the last one ended
+
+
+def unlocked(level: int, lessons: int) -> int:
+    """How many lessons are in the mix at `level`."""
+    return max(1, min(lessons, 1 + (level - 1) // LEVELS_PER_LESSON))
+
+
+def budget(ref: int, level: int) -> int:
+    """The most keys allowed at `level`; mirrors budget() in runner.lua."""
+    slack = max(0.0, 1 - (level - 1) / RAMP)
+    return ref + math.ceil(ref * slack) + (1 if slack > 0 else 0)
+
+
+def ladder(lessons: list[Lesson], start: int, length: int = RUNGS, seed: object = None) -> list[tuple[Task, int]]:
+    """The tasks to climb from level `start` on, as (task, version)."""
+    rng = random.Random(seed)
+    recent: deque[str] = deque(maxlen=8)
+    rungs = []
+    for level in range(start, start + length):
+        mix = lessons[: unlocked(level, len(lessons))]
+        lesson = mix[-1] if rng.random() < 0.5 else rng.choice(mix)
+        task = rng.choice([t for t in lesson.tasks if t.item_id not in recent] or lesson.tasks)
+        recent.append(task.item_id)
+        rungs.append((task, rng.randrange(task.versions)))
+    return rungs
+
+
+def summary(results: list, start: int) -> dict[str, int]:
+    climbed = sum(r.task.phase == "climb" and r.status == "solved" for r in results)
+    return {
+        "start": start,
+        "level": start + climbed,
+        "climbed": climbed,
+        "missed": sum(r.status in ("failed", "skipped") and r.task.phase != "learn" for r in results),
+        "fixed": sum(r.task.phase == "recall" and r.status == "solved" for r in results),
+    }