craftkit 0.3.0__py3-none-any.whl

craft_kit/study.py

@@ -0,0 +1,170 @@
+"""Study: gather evidence about the target into capture/, README.md first.
+
+Clean room (default): only what a visitor or user sees: screenshots and visible facts of a website,
+the person's pictures in reference/, and (with --allow-run) what a program prints when run.
+Deep: also look inside: a site's HTML, a folder's files and manifests, a program's strings."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import re
+import urllib.request
+from collections import Counter
+from pathlib import Path
+
+from . import browser, proc, tables
+from .ui import UI
+from .workspace import IGNORED, Project, write_atomic
+
+RUN_INPUTS: list[list[str]] = [[], ["--help"], ["--version"], ["-h"]]
+MANIFESTS = ["package.json", "Cargo.toml", "pyproject.toml", "go.mod", "requirements.txt", "setup.py", "Makefile", "CMakeLists.txt", "README.md", "README", "README.txt"]
+PICTURES = {".png", ".jpg", ".jpeg", ".webp", ".gif"}
+
+
+def study(p: Project, ui: UI) -> None:
+    t = p.state["target"]
+    cap = p.capture
+    if cap.exists():
+        shutil.rmtree(cap, ignore_errors=True)
+    cap.mkdir(parents=True, exist_ok=True)
+    notes = [
+        "# Evidence",
+        "",
+        f"Request: “{p.state['request']}”",
+        f"Target: {t['value'] or 'none (build from the request)'}",
+        f"Mode: {p.mode()}" + ("" if p.deep else " — nothing inside the original was read; don't read it either."),
+        "",
+    ]
+    if t["type"] == "website":
+        notes.append(_website(p, t["value"], ui))
+    elif t["type"] == "local":
+        path = Path(t["value"])
+        if p.deep:
+            notes.append(_inside(path, cap, ui))
+        else:
+            notes.append("## Clean room\n\nThe program, its files and its folder weren't opened. Build from the request, the pictures in reference/ and what it prints below (if anything). Ask the person about what can't be seen.\n")
+        if p.state.get("allow_run") and _runnable(path):
+            notes.append(_runs(path, cap, ui))
+        elif _runnable(path):
+            notes.append("It wasn't run (start the project with --allow-run to record what it prints).\n")
+    else:
+        notes.append("No target: build from the request alone.\n")
+    pics = sorted(x.name for x in p.reference.glob("*") if x.suffix.lower() in PICTURES) if p.reference.exists() else []
+    if pics:
+        notes.append("## Pictures from the person (reference/)\n\n" + "\n".join(f"- {n}" for n in pics) + "\n\nOpen each one and look closely.\n")
+    write_atomic(cap / "README.md", "\n".join(notes))
+    p.log(f"study done: {len(list(cap.rglob('*')))} files in capture/")
+
+
+def _website(p: Project, url: str, ui: UI) -> str:
+    out = []
+    with ui.live(f"photographing {url}", "study") as live:
+        shots, facts, problems = browser.capture(url, p.capture, tables.WIDTHS, facts=True, live=live)
+    if facts:
+        write_atomic(p.capture / "capture.json", json.dumps({"version": 1, "url": url, "widths": tables.WIDTHS, "facts": facts}, indent=1, ensure_ascii=False))
+    out.append("## Screenshots\n")
+    out += [f"- {s.name}" for s in shots] or ["None could be taken."]
+    out.append("\nOpen every screenshot and match it width by width: layout, spacing, sizes, colours, fonts, what changes on a phone.\n")
+    out.append(browser.facts_markdown(facts))
+    for prob in problems:
+        ui.note(prob)
+        out.append(f"> {prob}\n")
+    if p.deep:
+        try:
+            req = urllib.request.Request(url, headers={"User-Agent": "craftkit"})
+            with urllib.request.urlopen(req, timeout=30) as r:
+                html = r.read(2_000_000).decode("utf-8", "replace")
+            write_atomic(p.capture / "page.html", html)
+            out.append("Deep: the page's HTML as served is in page.html (rebuild what you learn; never paste it into app/).\n")
+        except (OSError, ValueError) as e:
+            out.append(f"Deep: the page's HTML couldn't be fetched ({e}).\n")
+    ui.step("done" if shots else "fail", "study", f"{len(shots)} screenshot(s)" + (", visible facts" if facts else ""))
+    return "\n".join(out)
+
+
+def _runnable(path: Path) -> bool:
+    return path.is_file() and os.access(path, os.X_OK)
+
+
+def _runs(program: Path, cap: Path, ui: UI) -> str:
+    runs = []
+    with ui.live(f"running {program.name} with {len(RUN_INPUTS)} inputs", "study") as live:
+        for args in RUN_INPUTS:
+            live.event("run", f"{program.name} {' '.join(args)}".strip())
+            r = proc.run([str(program), *args], cwd=str(cap), timeout=10, cap=16_000)
+            runs.append({"args": args, "code": r.code, "output": r.output[-16_000:], "timed_out": r.timed_out, "error": r.error})
+    write_atomic(cap / "runs.json", json.dumps({"version": 1, "program": program.name, "runs": runs}, indent=1, ensure_ascii=False))
+    lines = ["## What it prints (runs.json)", ""]
+    for run in runs:
+        first = (run["output"].strip().splitlines() or [run["error"] or "(nothing)"])[0][:100]
+        lines.append(f"- `{program.name} {' '.join(run['args'])}`: exit {run['code']} — {first}")
+    lines.append("\nThe rebuild must print the same for each input and exit the same way; the check reruns these inputs.\n")
+    ui.step("done", "runs", f"{len(runs)} runs recorded")
+    return "\n".join(lines)
+
+
+def _inside(path: Path, cap: Path, ui: UI) -> str:
+    out = ["## Deep: what's inside", ""]
+    if path.is_dir():
+        exts: Counter = Counter()
+        files = size = 0
+        top = sorted(x.name + ("/" if x.is_dir() else "") for x in path.iterdir())[:80]
+        for dirpath, dirnames, filenames in os.walk(path):
+            dirnames[:] = [d for d in dirnames if d not in IGNORED]
+            for n in filenames:
+                files += 1
+                exts[Path(n).suffix.lower() or "(none)"] += 1
+                try:
+                    size += (Path(dirpath) / n).stat().st_size
+                except OSError:
+                    pass
+            if files > 50_000:
+                break
+        out.append(f"{files} files, {size / 1e6:.1f} MB. Top level: " + ", ".join(top))
+        out.append("\nBy type: " + ", ".join(f"{e} {c}" for e, c in exts.most_common(15)))
+        man = cap / "manifests"
+        copied = []
+        for name in MANIFESTS:
+            src = path / name
+            if src.is_file() and src.stat().st_size < 200_000:
+                man.mkdir(exist_ok=True)
+                shutil.copyfile(src, man / name)
+                copied.append(name)
+        if copied:
+            out.append("\nCopied to capture/manifests/: " + ", ".join(copied) + " (read them first).")
+        stacks = [tc["file"] for tc in tables.TOOLCHAINS if (path / tc["file"]).exists()]
+        if stacks:
+            out.append(f"Built with: {', '.join(stacks)}.")
+        out.append(f"\nThe original folder is {path}: read what you need there, never change it.\n")
+    elif path.is_file():
+        st = path.stat()
+        out.append(f"{path.name}: {st.st_size / 1e6:.2f} MB.")
+        if proc.which("file"):
+            r = proc.run(["file", "-b", str(path)], timeout=20)
+            if r.ok:
+                out.append(f"Type: {r.output.strip()}")
+        found = _strings(path)
+        write_atomic(cap / "strings.txt", "\n".join(found))
+        out.append(f"\n{len(found)} readable strings saved to strings.txt (options, messages, names: clues to its features).\n")
+    ui.step("done", "inside", "inventory written")
+    return "\n".join(out)
+
+
+def _strings(path: Path, minimum: int = 6, limit: int = 3000, scan: int = 32_000_000) -> list[str]:
+    try:
+        with open(path, "rb") as f:
+            data = f.read(scan)
+    except OSError:
+        return []
+    found: list[str] = []
+    seen: set = set()
+    for m in re.finditer(rb"[\x20-\x7e\t]{%d,}" % minimum, data):
+        s = m.group().decode("ascii").strip()
+        if s and s not in seen:
+            seen.add(s)
+            found.append(s[:200])
+            if len(found) >= limit:
+                break
+    return found

craft_kit/tables.py

@@ -0,0 +1,154 @@
+"""Catalogues as data: kinds of thing made, stacks, toolchains and coding agents.
+Override or extend agents with ~/.config/craft/agents.json (same shape as AGENTS)."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+WIDTHS = [1440, 768, 390]  # desktop, tablet, phone: Study and Check photograph the same widths
+MAX_ROUNDS = 6  # refinement rounds per request (kept across runs; a new request resets it)
+GOOD_ENOUGH = 90.0  # stop refining once every scored check is at least this alike (percent)
+UNCHANGED_LIMIT = 2  # stop when the builder changes nothing this many turns in a row
+PLAYWRIGHT = "playwright@1.48.2"
+
+# A kind: how it's recognised (whole words, English and French), what the goal is, which checks judge it.
+KINDS: dict[str, dict] = {
+    "website": {
+        "words": ["website", "site", "webpage", "landing", "homepage", "page", "web"],
+        "goal": "a website that looks and behaves like the original at every screen width",
+        "checks": ["build", "web", "tests"],
+    },
+    "game": {
+        "words": ["game", "jeu", "gameplay", "arcade", "platformer", "puzzle"],
+        "goal": "a playable game with the same rules, controls, numbers and feel",
+        "checks": ["build", "selftest", "screenshot"],
+    },
+    "cli": {
+        "words": ["cli", "command", "commande", "console", "terminal", "shell", "script"],
+        "goal": "a command-line program that prints the same output and exits with the same codes",
+        "checks": ["build", "runs", "tests"],
+    },
+    "app": {
+        "words": ["app", "application", "desktop", "gui", "window", "fenêtre", "mobile"],
+        "goal": "an application with the same core features and screens",
+        "checks": ["build", "screenshot", "tests"],
+    },
+    "tool": {
+        "words": ["library", "librairie", "bibliothèque", "api", "server", "serveur", "service", "sdk", "package", "plugin", "outil", "tool"],
+        "goal": "software that does what the original does, verified by its own tests",
+        "checks": ["build", "tests"],
+    },
+}
+KIND_ORDER = ["game", "website", "cli", "app", "tool"]
+
+# A stack: phrases that ask for it (matched on " lower-case words "), and what the builder is told.
+STACKS: list[dict] = [
+    {"name": "Next.js (static export)", "asked_by": [" next js ", " nextjs "],
+     "steps": "Next.js App Router + TypeScript with output: 'export', trailingSlash: true and unoptimized images; build with `npm install && npm run build`; the site is app/out."},
+    {"name": "React + TypeScript (Vite)", "asked_by": [" react ", " vite "],
+     "steps": "Vite + React + TypeScript with base './'; build with `npm install && npm run build`; the site is app/dist."},
+    {"name": "Plain HTML and CSS", "asked_by": [" html ", " plain html ", " no framework ", " sans framework ", " static "],
+     "steps": "plain HTML and CSS (JavaScript only where needed), no build step; index.html at the top of app/, one file per page."},
+    {"name": "Electron", "asked_by": [" electron "],
+     "steps": "Electron + TypeScript or JavaScript, contextIsolation on, nodeIntegration off, IPC through a preload script; a `build` script that exits without opening a window."},
+    {"name": "Python", "asked_by": [" python ", " py "],
+     "steps": "Python 3.9+ with a pyproject.toml, standard library first; tests with pytest under app/tests."},
+    {"name": "Rust", "asked_by": [" rust ", " cargo "],
+     "steps": "a cargo project at app/ itself (app/Cargo.toml, app/src/); `cargo build` must succeed and `cargo test` must pass."},
+    {"name": "Go", "asked_by": [" go ", " golang "],
+     "steps": "a Go module at app/ itself; `go build ./...` must succeed and `go test ./...` must pass."},
+    {"name": "Node.js + TypeScript", "asked_by": [" node ", " nodejs ", " typescript ", " javascript ", " js ", " ts "],
+     "steps": "Node.js 18+ with TypeScript, a package.json `build` script and tests runnable with `npm test`."},
+]
+BUILDERS_CHOICE = {
+    "name": "Builder's choice",
+    "steps": "whatever their request names; otherwise choose the stack that best fits the request and what the original visibly uses, and prefer the simplest one that does the job. A website must build to static files (index.html at the top of a folder) that work when served as they are.",
+}
+
+# How a project builds and tests itself, found by the file that names the tool (first match wins).
+PY = os.path.basename(sys.executable) if sys.executable else "python3"
+TOOLCHAINS: list[dict] = [
+    {"file": "package.json", "install": ["npm", "install"], "build": ["npm", "run", "build", "--if-present"], "test": ["npm", "test", "--if-present"]},
+    {"file": "Cargo.toml", "build": ["cargo", "build"], "test": ["cargo", "test"]},
+    {"file": "go.mod", "build": ["go", "build", "./..."], "test": ["go", "test", "./..."]},
+    {"file": "pyproject.toml", "build": [PY, "-m", "compileall", "-q", "."], "test": [PY, "-m", "pytest", "-q"]},
+    {"file": "requirements.txt", "build": [PY, "-m", "compileall", "-q", "."], "test": [PY, "-m", "pytest", "-q"]},
+    {"file": "CMakeLists.txt", "build": ["cmake", "-S", ".", "-B", "build"], "test": ["ctest", "--test-dir", "build"]},
+    {"file": "Makefile", "build": ["make"], "test": ["make", "test"]},
+]
+NO_TESTS = ["no tests ran", "no tests found", "0 tests", "running 0 tests", "no test files", "missing script: \"test\"", "no tests to run", "collected 0 items"]
+SITE_DIRS = ["dist", "out", "build", "public", "."]
+
+# Coding agents, driven headless. The brief goes in on stdin (never argv: it can be long).
+_CLAUDE_TOOLS = ",".join(
+    ["Read", "Write", "Edit", "Glob", "Grep", "TodoWrite"]
+    + [f"Bash({p}:*)" for p in ["npm", "npx", "node", "pnpm", "yarn", "cargo", "rustc", "go", "python", "python3", "pip", "pytest", "make", "cmake", "craft", "ls", "mkdir", "cat"]]
+)
+AGENTS: dict[str, dict] = {
+    "claude": {
+        "argv": ["claude", "-p", "--output-format", "stream-json", "--verbose", "--permission-mode", "acceptEdits", "--allowedTools", _CLAUDE_TOOLS],
+        "stream": "claude-json",
+        "resume": ["--resume", "{session}"],
+        "lost": "No conversation found",
+    },
+    "codex": {"argv": ["codex", "exec", "--full-auto", "-"], "stream": "text"},
+    "gemini": {"argv": ["gemini", "--yolo"], "stream": "text"},
+}
+AGENT_ORDER = ["claude", "codex", "gemini"]
+
+
+def config_dir() -> Path:
+    if os.environ.get("CRAFT_CONFIG_DIR"):
+        return Path(os.environ["CRAFT_CONFIG_DIR"])
+    if os.environ.get("XDG_CONFIG_HOME"):
+        return Path(os.environ["XDG_CONFIG_HOME"]) / "craft"
+    return Path.home() / ".config" / "craft"
+
+
+def agents() -> dict[str, dict]:
+    table = {k: dict(v) for k, v in AGENTS.items()}
+    path = config_dir() / "agents.json"
+    try:
+        extra = json.loads(path.read_text("utf-8"))
+    except (OSError, ValueError):
+        return table
+    if isinstance(extra, dict):
+        for name, spec in extra.items():
+            if isinstance(spec, dict) and isinstance(spec.get("argv"), list) and all(isinstance(a, str) for a in spec["argv"]):
+                table[name] = {**table.get(name, {}), **spec}
+                if name not in AGENT_ORDER:
+                    AGENT_ORDER.append(name)
+    return table
+
+
+def words(text: str) -> str:
+    """Lower-case words padded with spaces, punctuation as spaces: "Next.js," -> " next js "."""
+    cleaned = "".join(ch if ch.isalnum() else " " for ch in text.lower())
+    return f" {' '.join(cleaned.split())} "
+
+
+def detect_kind(request: str, target_type: str) -> str:
+    w = words(request)
+    for kind in KIND_ORDER:
+        if any(f" {word} " in w for word in KINDS[kind]["words"]):
+            # "site" alone in a request about a game or CLI shouldn't win; KIND_ORDER puts game first.
+            return kind
+    return "website" if target_type == "website" else "tool"
+
+
+def detect_stack(request: str) -> dict:
+    w = words(request)
+    for s in STACKS:
+        if any(p in w for p in s["asked_by"]):
+            return s
+    return BUILDERS_CHOICE
+
+
+def stack_by_name(name: str) -> dict:
+    for s in STACKS:
+        if s["name"].lower() == name.lower() or name.lower() in words(s["name"]):
+            return s
+    return BUILDERS_CHOICE if name.lower() in ("", "builder's choice", "auto", "choice") else {"name": name, "steps": f"{name}, as the request asks."}

craft_kit/ui.py

@@ -0,0 +1,284 @@
+"""A minimal terminal interface: one line per step, a live feed of what's happening, one live line
+while something runs. Each stage has its colour (study sky, build blue, refine violet, check amber,
+ready green); NO_COLOR, a pipe or TERM=dumb give plain text, CRAFT_FEED=0 keeps only the live line."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+import threading
+import time
+from typing import Optional
+
+from . import banner
+
+ICONS = {"done": ("✓", "32"), "run": ("●", "36"), "todo": ("○", "2"), "fail": ("✗", "31"), "wait": ("?", "33"), "skip": ("–", "2")}
+FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+
+RGB = tuple  # (r, g, b)
+
+# The stages of the loop, each with its colour.
+STAGES: dict = {
+    "study": (70, 210, 255),
+    "build": (60, 125, 255),
+    "refine": (165, 95, 255),
+    "check": (255, 185, 60),
+    "ready": (80, 220, 130),
+}
+# Step lines whose name isn't a stage say which stage they belong to.
+STEP_STAGE = {"runs": "study", "inside": "study", "new": "ready", "answer": "build", "open": "ready", "skill": "ready"}
+
+# What the builder does, by kind: icon, verb, colour. None = dim.
+KINDS: dict = {
+    "read": ("◇", "read", (120, 200, 255)),
+    "edit": ("✎", "edit", (90, 225, 140)),
+    "write": ("✚", "write", (60, 235, 170)),
+    "run": ("❯", "run", (255, 200, 80)),
+    "search": ("⌕", "search", (205, 140, 255)),
+    "web": ("◎", "web", (80, 165, 255)),
+    "plan": ("☰", "plan", (245, 115, 200)),
+    "agent": ("◆", "agent", (150, 160, 255)),
+    "tool": ("▸", "tool", (180, 180, 200)),
+    "fail": ("✗", "failed", (240, 85, 95)),
+    "say": ("“", "", None),
+    "out": ("·", "", None),
+}
+
+
+def _tty(stream) -> bool:
+    try:
+        return stream.isatty() and not os.environ.get("NO_COLOR") and os.environ.get("TERM") != "dumb"
+    except (AttributeError, ValueError):
+        return False
+
+
+def elapsed(seconds: float) -> str:
+    s = int(seconds)
+    return f"{s // 60}m{s % 60:02d}s" if s >= 60 else f"{s}s"
+
+
+def clock(seconds: float) -> str:
+    s = int(seconds)
+    return f"{s // 60}:{s % 60:02d}"
+
+
+def fit(text: str, room: int) -> str:
+    text = " ".join(text.split())
+    return text if len(text) <= room else text[: max(0, room - 1)] + "…"
+
+
+def stage_of(name: str) -> Optional[str]:
+    return name if name in STAGES else STEP_STAGE.get(name)
+
+
+def _mix(a: RGB, b: RGB, k: float) -> RGB:
+    return tuple(round(x + (y - x) * k) for x, y in zip(a, b))
+
+
+class UI:
+    def __init__(self, stream=None):
+        self.out = stream or sys.stderr
+        self.fancy = _tty(self.out)
+        self.feed = os.environ.get("CRAFT_FEED", "1").lower() not in ("0", "off", "no", "false")
+        self._lock = threading.Lock()
+        self._live: Live | None = None
+
+    # colours ---------------------------------------------------------------
+    def c(self, code: str, text: str) -> str:
+        return f"\033[{code}m{text}\033[0m" if self.fancy else text
+
+    def rgb(self, colour: Optional[RGB], text: str, bold: bool = False, italic: bool = False, dim: bool = False) -> str:
+        if not self.fancy or not text:
+            return text
+        style = ("\033[1m" if bold else "") + ("\033[3m" if italic else "") + ("\033[2m" if dim else "")
+        return f"{style}{banner.fg(colour) if colour else ''}{text}\033[0m"
+
+    def dim(self, t: str) -> str:
+        return self.c("2", t)
+
+    def bold(self, t: str) -> str:
+        return self.c("1", t)
+
+    def red(self, t: str) -> str:
+        return self.c("31", t)
+
+    def green(self, t: str) -> str:
+        return self.c("32", t)
+
+    def yellow(self, t: str) -> str:
+        return self.c("33", t)
+
+    def width(self) -> int:
+        return max(40, min(shutil.get_terminal_size((80, 20)).columns, 100))
+
+    # output ------------------------------------------------------------------
+    def say(self, text: str = "") -> None:
+        with self._lock:
+            if self._live is not None:
+                self._live.clear()
+            print(text, file=self.out, flush=True)
+
+    def header(self, name: str, right: str) -> None:
+        w = self.width()
+        left = f"craft · {name}"
+        gap = max(1, w - len(left) - len(right) - 2)
+        self.say(f" {self.bold(left)}{' ' * gap}{self.dim(right)}")
+
+    def stage(self, name: str, detail: str = "") -> None:
+        """A coloured rule that opens a stage: ` ▍build  claude · turn 3 ─────────`."""
+        colour = STAGES.get(name)
+        detail = fit(detail, self.width() - len(name) - 12)
+        rule = "─" * max(3, self.width() - len(name) - len(detail) - 8)
+        if not self.fancy:
+            self.say(f"\n -- {name}  {detail}".rstrip())
+            return
+        self.say("")
+        self.say(f" {self.rgb(colour, '▍' + name, bold=True)}  {detail}{' ' if detail else ''}{self.rgb(colour, rule, dim=True)}")
+
+    def step(self, state: str, name: str, detail: str = "", stage: Optional[str] = None) -> None:
+        icon, code = ICONS.get(state, ICONS["todo"])
+        quiet = state in ("todo", "skip")
+        detail = self.dim(detail) if quiet else detail
+        colour = STAGES.get(stage or stage_of(name) or "")
+        label = f"{name:<7}"
+        label = self.dim(label) if quiet else (self.rgb(colour, label, bold=True) if colour else label)
+        self.say(f" {self.c(code, icon)} {label} {detail}".rstrip())
+
+    def note(self, text: str) -> None:
+        for line in text.splitlines() or [""]:
+            self.say(f"   {self.dim('│')} {line}")
+
+    def error(self, text: str) -> None:
+        self.say(f" {self.red('✗')} {text}")
+
+    def live(self, label: str, stage: Optional[str] = None) -> "Live":
+        return Live(self, label, stage)
+
+    # input -------------------------------------------------------------------
+    def interactive(self) -> bool:
+        return sys.stdin.isatty() and self.fancy
+
+    def ask(self, prompt: str) -> str:
+        with self._lock:
+            if self._live is not None:
+                self._live.clear()
+        try:
+            return input(f" {self.c('33', '?')} {prompt} ").strip()
+        except EOFError:
+            return ""
+
+    def choose(self, question: str, choices: list[str]) -> str:
+        self.say(f" {self.c('33', '?')} {question}")
+        for i, ch in enumerate(choices, 1):
+            self.say(f"     {self.bold(str(i))}  {ch}")
+        raw = self.ask("number, or your own answer:")
+        if raw.isdigit() and 1 <= int(raw) <= len(choices):
+            return choices[int(raw) - 1]
+        return raw
+
+
+class Live:
+    """While something runs: a feed of what it does (one line per action, kept on screen) above a
+    single line that redraws in place (spinner, shimmering label, elapsed time, latest activity)."""
+
+    def __init__(self, ui: UI, label: str, stage: Optional[str] = None):
+        self.ui = ui
+        self.label = label
+        self.colour: RGB = STAGES.get(stage or "", (150, 160, 255))
+        self.detail = ""
+        self.start = time.monotonic()
+        self.counts: dict = {}
+        self._last_event = ""
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def __enter__(self) -> "Live":
+        if self.ui.fancy:
+            self.ui._live = self
+            self._thread = threading.Thread(target=self._spin, daemon=True)
+            self._thread.start()
+        else:
+            print(f"   … {self.label}", file=self.ui.out, flush=True)
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=1)
+        with self.ui._lock:
+            self.clear()
+            self.ui._live = None
+
+    def update(self, detail: str) -> None:
+        self.detail = " ".join(detail.split())
+
+    def event(self, kind: str, text: str, count: bool = True) -> None:
+        """One action, kept in the feed: `   1:42 ✎ edit    src/main.rs`."""
+        text = " ".join(text.split())
+        if not text:
+            return
+        self.update(text)
+        key = f"{kind}\0{text}"
+        if key == self._last_event:  # the same line twice in a row says nothing new
+            return
+        self._last_event = key
+        if count and kind not in ("say", "out"):
+            self.counts[kind] = self.counts.get(kind, 0) + 1
+        if not self.ui.feed:
+            return
+        icon, verb, colour = KINDS.get(kind, KINDS["tool"])
+        stamp = clock(time.monotonic() - self.start)
+        head = f"{icon} {verb:<7}" if verb else f"{icon} "
+        room = self.ui.width() - len(stamp) - len(head) - 6
+        body = fit(text, room)
+        u = self.ui
+        if kind in ("say", "out"):
+            line = f"   {u.dim(stamp)} {u.dim(head)}{u.rgb(None, body, italic=kind == 'say', dim=True)}"
+        else:
+            line = f"   {u.dim(stamp)} {u.rgb(colour, head, bold=True)}{u.rgb(colour, body) if kind == 'fail' else body}"
+        u.say(line)
+
+    def tally(self) -> str:
+        """`2m14s · 18 actions: 6 edit, 5 read, 4 run`."""
+        counts = {k: n for k, n in self.counts.items() if k != "fail"}
+        total = sum(counts.values())
+        out = elapsed(time.monotonic() - self.start)
+        if total:
+            parts = sorted(counts.items(), key=lambda kv: -kv[1])
+            out += f" · {total} action{'s' if total > 1 else ''}: " + ", ".join(f"{n} {KINDS.get(k, KINDS['tool'])[1] or k}" for k, n in parts)
+        if self.counts.get("fail"):
+            out += f" · {self.counts['fail']} failed"
+        return out
+
+    def clear(self) -> None:
+        if self.ui.fancy:
+            self.ui.out.write("\r\033[2K")
+            self.ui.out.flush()
+
+    def _shimmer(self, text: str, i: int) -> str:
+        """The label in its stage colour, a bright band sweeping across it."""
+        base = _mix(self.colour, (40, 40, 60), 0.25)
+        n = len(text) + 8
+        pos = (i * 0.6) % n - 4
+        cells = []
+        for x, ch in enumerate(text):
+            k = max(0.0, 1.0 - abs(x - pos) / 4.0)
+            cells.append(f"{banner.fg(_mix(base, (255, 255, 255), 0.7 * k))}{ch}")
+        return "\033[1m" + "".join(cells) + "\033[0m"
+
+    def _spin(self) -> None:
+        i = 0
+        while not self._stop.wait(0.1):
+            i += 1
+            u = self.ui
+            frame = FRAMES[i % len(FRAMES)]
+            time_s = elapsed(time.monotonic() - self.start)
+            done = sum(n for k, n in self.counts.items() if k != "fail")
+            meta = f" · {time_s}" + (f" · {done}" if done else "")
+            room = u.width() - 1 - 5 - len(self.label) - len(meta)
+            detail = f" · {fit(self.detail, room - 3)}" if self.detail and room > 8 else ""
+            text = f"   {u.rgb(self.colour, frame, bold=True)} {self._shimmer(self.label, i)}{u.dim(meta)}{u.dim(detail)}"
+            with u._lock:
+                u.out.write("\r\033[2K" + text)
+                u.out.flush()