hubble-cli 4.1.2__tar.gz → 4.2.0__tar.gz

{hubble_cli-4.1.2/hubble_cli.egg-info → hubble_cli-4.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: hubble-cli
-Version: 4.1.2
-Summary: Hubble: agentic coding CLI for AIHub and other OpenAI-compatible APIs
+Version: 4.2.0
+Summary: Agentic coding CLI for OpenAI-compatible APIs, Claude, and local LLMs
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Hamdayrabby/hubble-cli
 Project-URL: Repository, https://github.com/Hamdayrabby/hubble-cli
@@ -15,6 +15,8 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development
 Classifier: Topic :: Utilities
 Requires-Python: >=3.10
@@ -24,6 +26,7 @@ Requires-Dist: httpx>=0.25.0
 Requires-Dist: rich>=13.0
 Requires-Dist: prompt_toolkit>=3.0.40
 Requires-Dist: keyring>=24
+Requires-Dist: anthropic>=1.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Dynamic: license-file
@@ -42,6 +45,14 @@ pipx install hubble-cli
 ```
 (or `pip install --user hubble-cli`; the latest unreleased code: `pipx install git+https://github.com/Hamdayrabby/hubble-cli.git`)
 
+**"hubble is not recognized" after `pip install`?** pip put the command in a folder that isn't on your
+PATH (it warns: *"The script hubble.exe is installed in '...\Scripts' which is not on PATH"*). Either run
+it as `python -m hubble`, or fix it once with:
+```
+python -m hubble --add-to-path
+```
+then open a new terminal and run `hubble`. (pipx avoids this: `pipx ensurepath` sets PATH up for you.)
+
 Upgrade with `pipx upgrade hubble-cli` (or `pip install -U hubble-cli`). Hubble tells you when a new
 version is out — it checks PyPI at most once a day; set `"update_check": false` to turn that off.
 
@@ -349,8 +360,13 @@ Allow rules never apply to chained commands (`&&`, `;`, `|`, redirects), so `she
 
 ## Providers (extra base URLs and API keys)
 
-Any OpenAI-compatible API can be added next to the built-in AIHub gateway: OpenRouter, Groq, OpenAI, Mistral,
-Gemini's OpenAI endpoint, a local Ollama server, and others.
+Add providers next to the built-in AIHub gateway. The `/provider add` list has presets for:
+- **Claude (Anthropic)** — native Messages API (not an OpenAI shim): tool use, images, thinking, prompt caching
+  of the system prompt, and the real context window of each model. An `ANTHROPIC_API_KEY` in your environment is
+  picked up automatically as a provider named `anthropic` (`ANTHROPIC_BASE_URL` too, for a proxy).
+- **OpenAI-compatible:** OpenAI, OpenRouter, Gemini, Groq, Mistral, DeepSeek, xAI (Grok), Together, Fireworks,
+  Cerebras, NVIDIA, Moonshot (Kimi), and local Ollama / LM Studio servers.
+- **Custom URL**, either OpenAI-compatible or Anthropic-compatible (a proxy or gateway speaking `/v1/messages`).
 
 1. Type `/provider add`, or open `/provider` and choose **+ Add a provider**.
 2. Pick a known provider or **Custom URL...**, then paste the API key. The key is hidden as you type.
@@ -368,7 +384,7 @@ Extra providers are stored in `~/.hubble/providers.json`. Their API keys go to y
 (Windows Credential Manager, macOS Keychain, or Secret Service on Linux); only where no credential store
 exists (headless Linux, containers) are they written into that file in plain text. `/provider secure` moves
 keys saved by older versions into the credential store.
-Their model lists are stored in `~/.hubble/models/<name>.json`. When a model is rate limited or down, Hubble retries that request with a fallback that the current provider actually has, in this order: the fallback you picked with `/fallback`, then `fallback_model` if the provider has it, then the provider's fastest verified model, then `fallback_model` on the built-in hubble provider. Sub-agents use the same route. `/fallback off` disables it for a provider.
+Their model lists are stored in `~/.hubble/models/<name>.json`. When a model is rate limited or down, Hubble retries that request with a fallback that the current provider actually has, in this order: the fallback you picked with `/fallback`, then `fallback_model` if the provider has it, then the provider's fastest verified model, then `fallback_model` on the built-in `aihub` provider. Sub-agents use the same route. `/fallback off` disables it for a provider.
 
 ## Project memory
 

{hubble_cli-4.1.2 → hubble_cli-4.2.0}/README.md

@@ -12,6 +12,14 @@ pipx install hubble-cli
 ```
 (or `pip install --user hubble-cli`; the latest unreleased code: `pipx install git+https://github.com/Hamdayrabby/hubble-cli.git`)
 
+**"hubble is not recognized" after `pip install`?** pip put the command in a folder that isn't on your
+PATH (it warns: *"The script hubble.exe is installed in '...\Scripts' which is not on PATH"*). Either run
+it as `python -m hubble`, or fix it once with:
+```
+python -m hubble --add-to-path
+```
+then open a new terminal and run `hubble`. (pipx avoids this: `pipx ensurepath` sets PATH up for you.)
+
 Upgrade with `pipx upgrade hubble-cli` (or `pip install -U hubble-cli`). Hubble tells you when a new
 version is out — it checks PyPI at most once a day; set `"update_check": false` to turn that off.
 
@@ -319,8 +327,13 @@ Allow rules never apply to chained commands (`&&`, `;`, `|`, redirects), so `she
 
 ## Providers (extra base URLs and API keys)
 
-Any OpenAI-compatible API can be added next to the built-in AIHub gateway: OpenRouter, Groq, OpenAI, Mistral,
-Gemini's OpenAI endpoint, a local Ollama server, and others.
+Add providers next to the built-in AIHub gateway. The `/provider add` list has presets for:
+- **Claude (Anthropic)** — native Messages API (not an OpenAI shim): tool use, images, thinking, prompt caching
+  of the system prompt, and the real context window of each model. An `ANTHROPIC_API_KEY` in your environment is
+  picked up automatically as a provider named `anthropic` (`ANTHROPIC_BASE_URL` too, for a proxy).
+- **OpenAI-compatible:** OpenAI, OpenRouter, Gemini, Groq, Mistral, DeepSeek, xAI (Grok), Together, Fireworks,
+  Cerebras, NVIDIA, Moonshot (Kimi), and local Ollama / LM Studio servers.
+- **Custom URL**, either OpenAI-compatible or Anthropic-compatible (a proxy or gateway speaking `/v1/messages`).
 
 1. Type `/provider add`, or open `/provider` and choose **+ Add a provider**.
 2. Pick a known provider or **Custom URL...**, then paste the API key. The key is hidden as you type.
@@ -338,7 +351,7 @@ Extra providers are stored in `~/.hubble/providers.json`. Their API keys go to y
 (Windows Credential Manager, macOS Keychain, or Secret Service on Linux); only where no credential store
 exists (headless Linux, containers) are they written into that file in plain text. `/provider secure` moves
 keys saved by older versions into the credential store.
-Their model lists are stored in `~/.hubble/models/<name>.json`. When a model is rate limited or down, Hubble retries that request with a fallback that the current provider actually has, in this order: the fallback you picked with `/fallback`, then `fallback_model` if the provider has it, then the provider's fastest verified model, then `fallback_model` on the built-in hubble provider. Sub-agents use the same route. `/fallback off` disables it for a provider.
+Their model lists are stored in `~/.hubble/models/<name>.json`. When a model is rate limited or down, Hubble retries that request with a fallback that the current provider actually has, in this order: the fallback you picked with `/fallback`, then `fallback_model` if the provider has it, then the provider's fastest verified model, then `fallback_model` on the built-in `aihub` provider. Sub-agents use the same route. `/fallback off` disables it for a provider.
 
 ## Project memory
 

hubble_cli-4.2.0/hubble/__init__.py

@@ -0,0 +1,3 @@
+"""Hubble: an agentic coding CLI for OpenAI-compatible APIs, Claude, and local LLMs."""
+
+__version__ = "4.2.0"

{hubble_cli-4.1.2 → hubble_cli-4.2.0}/hubble/agent.py

@@ -96,7 +96,8 @@ class Agent:
                  permissions: Permissions, events: Events, session: Optional[Session] = None,
                  tools: Optional[List[Tool]] = None, system_override: Optional[str] = None):
         self.provider = provider
-        self.provider_name: str = settings.get("provider") or "hubble"
+        from hubble.providers import normalize_provider_name
+        self.provider_name: str = normalize_provider_name(settings.get("provider"))
         self.fallback_client: Optional[OpenAICompatProvider] = provider
         # (provider_name, model) -> (client, fallback_model) or None; set by the REPL/headless runner.
         self.fallback_resolver = None
@@ -294,6 +295,8 @@ class Agent:
             if not text and not result.tool_calls:
                 text = "(empty response)"  # some backends reject empty assistant messages
             message: Dict[str, Any] = {"role": "assistant", "content": text}
+            if result.raw_content:
+                message["_anthropic_content"] = result.raw_content
             if result.tool_calls:
                 message["tool_calls"] = [{"id": c.id, "type": "function",
                                           "function": {"name": c.name, "arguments": c.arguments}}

hubble_cli-4.2.0/hubble/anthropic_provider.py

@@ -0,0 +1,256 @@
+"""Native Claude provider (Anthropic Messages API) with the same interface as OpenAICompatProvider.
+
+Hubble keeps its conversation history in OpenAI chat format; this module translates it to
+Messages API requests (system prompt, content blocks, tool_use / tool_result, images) and the
+streamed reply back into a TurnResult. The assistant's own content blocks (thinking blocks with
+their signatures included) are kept on the message under `_anthropic_content` and sent back
+unchanged on the next request, as the API expects when continuing a tool-use turn.
+
+Uses the official `anthropic` SDK: it handles SSE parsing, retries (429 / 5xx / 529 overloaded)
+and partial tool-input JSON.
+"""
+
+import json
+import re
+import time
+from typing import Any, Callable, Dict, List, Optional
+from urllib.parse import urlparse
+
+from hubble.provider import ProviderError, ToolCall, TurnResult, parse_arguments
+
+DEFAULT_BASE_URL = "https://api.anthropic.com"
+# Models where the API's server-side refusal fallback is recommended (and supported).
+FALLBACK_MODELS = ("claude-opus-5", "claude-fable-5-1", "claude-mythos-5-1")
+FALLBACK_BETA = "server-side-fallback-2026-07-01"
+STOP_REASONS = {"end_turn": "stop", "stop_sequence": "stop", "tool_use": "tool_calls",
+                "max_tokens": "length", "refusal": "refusal", "pause_turn": "pause_turn"}
+ID_RX = re.compile(r"[^a-zA-Z0-9_-]")
+
+
+def anthropic_base_url(url: str) -> str:
+    """The SDK adds /v1/... itself, so drop a trailing /v1 that normalize_base_url may have added."""
+    url = (url or DEFAULT_BASE_URL).strip().rstrip("/")
+    return url[:-3] if url.endswith("/v1") else url
+
+
+def _tool_id(raw: str) -> str:
+    """Tool-use ids must match ^[a-zA-Z0-9_-]+$; ids from other providers may not."""
+    return ID_RX.sub("_", raw or "") or "toolu_x"
+
+
+def _image_block(url: str) -> Optional[Dict[str, Any]]:
+    m = re.match(r"^data:(image/[\w.+-]+);base64,(.+)$", url or "", re.DOTALL)
+    if m:
+        return {"type": "image", "source": {"type": "base64", "media_type": m.group(1), "data": m.group(2)}}
+    if url.startswith(("http://", "https://")):
+        return {"type": "image", "source": {"type": "url", "url": url}}
+    return None
+
+
+def _user_blocks(content: Any) -> List[Dict[str, Any]]:
+    if isinstance(content, str):
+        return [{"type": "text", "text": content}] if content else []
+    blocks = []
+    for part in content or []:
+        if not isinstance(part, dict):
+            continue
+        if part.get("type") == "text" and part.get("text"):
+            blocks.append({"type": "text", "text": part["text"]})
+        elif part.get("type") == "image_url":
+            img = _image_block((part.get("image_url") or {}).get("url", ""))
+            if img:
+                blocks.append(img)
+    return blocks
+
+
+def to_anthropic(messages: List[Dict[str, Any]]):
+    """OpenAI-format history -> (system text, Messages API messages)."""
+    system_parts: List[str] = []
+    out: List[Dict[str, Any]] = []
+
+    def add(role: str, blocks: List[Dict[str, Any]]):
+        if not blocks:
+            return
+        if out and out[-1]["role"] == role:
+            out[-1]["content"].extend(blocks)  # tool results of one turn share a single user message
+        else:
+            out.append({"role": role, "content": list(blocks)})
+
+    for i, m in enumerate(messages):
+        role = m.get("role")
+        if role == "system":
+            if i == 0:
+                system_parts.append(m.get("content") or "")
+            else:
+                add("user", [{"type": "text", "text": f"<system-note>\n{m.get('content') or ''}\n</system-note>"}])
+        elif role == "user":
+            add("user", _user_blocks(m.get("content")))
+        elif role == "assistant":
+            raw = m.get("_anthropic_content")
+            if raw:
+                add("assistant", [dict(b) for b in raw])  # exact blocks from Claude, thinking included
+                continue
+            blocks: List[Dict[str, Any]] = []
+            text = m.get("content") or ""
+            if isinstance(text, str) and text.strip():
+                blocks.append({"type": "text", "text": text})
+            for tc in m.get("tool_calls") or []:
+                fn = tc.get("function") or {}
+                try:
+                    args = parse_arguments(fn.get("arguments") or "{}")
+                except ValueError:
+                    args = {}
+                blocks.append({"type": "tool_use", "id": _tool_id(tc.get("id", "")), "name": fn.get("name", ""),
+                               "input": args})
+            add("assistant", blocks or [{"type": "text", "text": "(no content)"}])
+        elif role == "tool":
+            add("user", [{"type": "tool_result", "tool_use_id": _tool_id(m.get("tool_call_id", "")),
+                          "content": m.get("content") or "(no output)",
+                          **({"is_error": True} if str(m.get("content", "")).startswith(("Error:", "Permission denied"))
+                             else {})}])
+    if out and out[0]["role"] != "user":
+        out.insert(0, {"role": "user", "content": [{"type": "text", "text": "(conversation continues)"}]})
+    return "\n\n".join(p for p in system_parts if p), out
+
+
+def to_anthropic_tools(tools: Optional[List[Dict[str, Any]]]) -> List[Dict[str, Any]]:
+    out = []
+    for t in tools or []:
+        fn = t.get("function") or t
+        schema = fn.get("parameters") or {"type": "object", "properties": {}}
+        # Stream large tool inputs (file contents) as they are generated; Hubble validates every
+        # parsed input against the tool's schema before running it.
+        out.append({"name": fn["name"], "description": fn.get("description", "")[:4096],
+                    "input_schema": schema, "eager_input_streaming": True})
+    return out
+
+
+class AnthropicProvider:
+    """Talks to Claude through the official SDK. Same methods as OpenAICompatProvider."""
+
+    kind = "anthropic"
+
+    def __init__(self, base_url: str, api_key: str, client=None, max_retries: int = 3):
+        import anthropic
+        from hubble import __version__
+        self._anthropic = anthropic
+        self.base_url = anthropic_base_url(base_url)
+        self.api_key = api_key
+        self.client = client or anthropic.Anthropic(
+            api_key=api_key, base_url=self.base_url, max_retries=max_retries, timeout=600.0,
+            default_headers={"User-Agent": f"hubble-cli/{__version__} (+https://github.com/Hamdayrabby/hubble-cli)"})
+        # Server-side fallbacks are a first-party API feature; proxies and gateways may reject them.
+        self.first_party = urlparse(self.base_url).hostname == "api.anthropic.com"
+
+    # ----- errors ---------------------------------------------------------
+
+    def _error(self, e: Exception) -> ProviderError:
+        a = self._anthropic
+        if isinstance(e, a.APIStatusError):
+            msg = getattr(e, "message", None) or str(e)
+            return ProviderError(f"HTTP {e.status_code}: {str(msg)[:200]}", e.status_code)
+        if isinstance(e, a.APIConnectionError):
+            return ProviderError(f"{type(e).__name__}: {e}")  # status None -> transient
+        return ProviderError(f"{type(e).__name__}: {e}", 400)
+
+    # ----- requests -------------------------------------------------------
+
+    def _params(self, model: str, messages, tools, max_tokens: int) -> Dict[str, Any]:
+        system, msgs = to_anthropic(messages)
+        params: Dict[str, Any] = {"model": model, "max_tokens": max_tokens, "messages": msgs}
+        if system:
+            # Cache the stable prefix (tools + system prompt) across the turns of a session.
+            params["system"] = [{"type": "text", "text": system, "cache_control": {"type": "ephemeral"}}]
+        if tools:
+            params["tools"] = to_anthropic_tools(tools)
+        # No temperature and no thinking config: current Claude models reject sampling
+        # parameters, and pick their own (adaptive) thinking by default.
+        return params
+
+    def _use_fallbacks(self, model: str) -> bool:
+        return self.first_party and any(model == m or model.startswith(m + "-") for m in FALLBACK_MODELS)
+
+    def stream(self, model: str, messages: List[Dict[str, Any]], tools: Optional[List[Dict]] = None,
+               temperature: float = 0.3, max_tokens: int = 8192,
+               on_text: Optional[Callable[[str], None]] = None,
+               on_reasoning: Optional[Callable[[str], None]] = None) -> TurnResult:
+        # Thinking counts against max_tokens and the reply is streamed (no timeout risk), so give
+        # the model room: Hubble's generic 8192 default would cut deep answers short.
+        params = self._params(model, messages, tools, max(max_tokens, 32000))
+        for attempt in range(3):
+            try:
+                return self._stream_once(model, params, on_text, on_reasoning)
+            except ValueError as e:
+                # Tool-input JSON the SDK could not parse at all (possible with eager input
+                # streaming). No tool_use id exists to answer, so re-issue the turn.
+                if attempt == 2:
+                    raise ProviderError(f"Claude sent unparseable tool input: {e}", 400) from None
+            except self._anthropic.APIError as e:
+                raise self._error(e) from None
+        raise ProviderError("unreachable")
+
+    def _stream_once(self, model, params, on_text, on_reasoning) -> TurnResult:
+        start = time.time()
+        result = TurnResult()
+        if self._use_fallbacks(model):
+            ctx = self.client.beta.messages.stream(**params, betas=[FALLBACK_BETA], fallbacks="default")
+        else:
+            ctx = self.client.messages.stream(**params)
+        with ctx as stream:
+            for event in stream:
+                if event.type == "text" and event.text:
+                    if not result.ttft_ms:
+                        result.ttft_ms = round((time.time() - start) * 1000)
+                    if on_text:
+                        on_text(event.text)
+                elif event.type == "thinking" and getattr(event, "thinking", ""):
+                    if on_reasoning:
+                        on_reasoning(event.thinking)
+            final = stream.get_final_message()
+        data = final.to_dict()
+        blocks = data.get("content") or []
+        result.text = "".join(b.get("text", "") for b in blocks if b.get("type") == "text")
+        result.reasoning = "".join(b.get("thinking", "") for b in blocks if b.get("type") == "thinking")
+        stop = data.get("stop_reason")
+        result.finish_reason = STOP_REASONS.get(stop, stop)
+        if stop != "max_tokens":
+            # On max_tokens a tool input may be cut off mid-JSON: never run it.
+            result.tool_calls = [ToolCall(b["id"], b["name"], json.dumps(b.get("input") or {}))
+                                 for b in blocks if b.get("type") == "tool_use"]
+        u = data.get("usage") or {}
+        prompt = sum(int(u.get(k) or 0) for k in ("input_tokens", "cache_read_input_tokens",
+                                                   "cache_creation_input_tokens"))
+        result.usage = {"prompt_tokens": prompt, "completion_tokens": int(u.get("output_tokens") or 0),
+                        "total_tokens": prompt + int(u.get("output_tokens") or 0)}
+        if stop != "max_tokens":
+            # Echo Claude's own blocks back next turn (keeps thinking signatures intact).
+            result.raw_content = blocks
+        result.duration = time.time() - start
+        return result
+
+    def complete(self, model: str, messages: List[Dict[str, Any]], max_tokens: int = 2048,
+                 temperature: float = 0.2) -> str:
+        params = self._params(model, messages, None, max_tokens)
+        try:
+            with self.client.messages.stream(**params) as stream:
+                final = stream.get_final_message()
+        except self._anthropic.APIError as e:
+            raise self._error(e) from None
+        return "".join(b.text for b in final.content if b.type == "text")
+
+    def ping(self, model: str) -> Dict[str, Any]:
+        start = time.time()
+        try:
+            text = self.complete(model, [{"role": "user", "content": "Reply OK"}], max_tokens=64)
+            return {"ok": True, "latency_ms": round((time.time() - start) * 1000), "msg": text.strip()[:60]}
+        except ProviderError as e:
+            return {"ok": False, "latency_ms": round((time.time() - start) * 1000), "msg": str(e)[:120]}
+
+    def list_models(self) -> List[Dict[str, Any]]:
+        """[{id, context_length, max_output}] from GET /v1/models."""
+        try:
+            return [{"id": m.id, "context_length": getattr(m, "max_input_tokens", None),
+                     "max_output": getattr(m, "max_tokens", None)} for m in self.client.models.list()]
+        except self._anthropic.APIError as e:
+            raise self._error(e) from None
+

{hubble_cli-4.1.2 → hubble_cli-4.2.0}/hubble/banner.py

@@ -299,6 +299,157 @@ def space_scene(width: int, t: float = 2.4, art: _Art = FULL) -> Text:
     return _grid_text(grid).append("\n")
 
 
+# ----- retro arcade scene (Space Invaders style) ----------------------------
+#
+# Also a pure function of t: invaders march in discrete steps like the 1978 cabinet, the ship
+# glides and fires on a fixed rhythm, and which invaders are gone is replayed from the shots
+# fired so far in the current wave, so any frame can be drawn on its own.
+
+INVADERS = [  # (frame A, frame B, color); one row each, top to bottom
+    ("▞█▚", "▚█▞", "#ff5fd7"),
+    ("▛▀▜", "▙▄▟", "#00d7ff"),
+]
+_SHIP_ROWS = [
+    "▲",
+    "▟█▙",
+    "▗▄▄▄▟█████▙▄▄▄▖",
+    "◢████ H U B B L E ████◣",
+    "▀▀▀▜█████████▛▀▀▀",
+    "▀▼▀   ▀▼▀",
+]
+SHIP_W = max(len(r) for r in _SHIP_ROWS)
+SHIP = [r.center(SHIP_W) for r in _SHIP_ROWS]  # the HUBBLE starship, nose on top
+UFO = "<=●=>"
+
+
+class _Arcade:
+    height = 5 + len(SHIP)  # score/UFO row, 2 invader rows, 2 rows of open space, the ship
+    width = 44              # smallest field that still looks like a formation
+    COLS = 8            # invaders per row
+    GAP = 5             # columns from one invader to the next
+    STEP = 0.45         # seconds per march step
+    SHOT_EVERY = 0.7
+    SHOT_SPEED = 14.0   # rows per second
+    WAVE = 14.0         # seconds before a fresh wave marches in
+
+    def field(self, width: int, left: Optional[int] = None) -> Tuple[int, int]:
+        """(left, field width) of the play area inside a grid `width` wide; centered by default."""
+        fw = max(self.width, min(width - 4, 76))
+        if left is None:
+            left = max(2, (width - fw) // 2)
+        return left, fw
+
+    def _march(self, t: float, span: int) -> int:
+        """Formation x offset: steps right, then left, one column per STEP (triangle wave)."""
+        steps = int(t / self.STEP)
+        period = 2 * span
+        k = steps % period if period else 0
+        return k if k <= span else period - k
+
+    def _ship_x(self, t: float, fw: int) -> float:
+        """Left column of the ship: cruises around the middle of the field."""
+        room = max(0, fw - SHIP_W)
+        return room / 2 + room / 2 * 0.85 * math.sin(t * 0.6)
+
+    def state(self, t: float, fw: int):
+        """(offset, dead {(row, i)}, explosions [(row, col, age)], bullets [(y, x)], score)."""
+        wave_t = t % self.WAVE
+        wave_start = t - wave_t
+        formation = (self.COLS - 1) * self.GAP + 3
+        span = max(0, fw - formation)
+        dead, booms, bullets, score = set(), [], [], 0
+        n = int(wave_t / self.SHOT_EVERY)
+        for k in range(n + 1):
+            fired = wave_start + k * self.SHOT_EVERY
+            if fired > t:
+                break
+            x = int(round(self._ship_x(fired, fw))) + SHIP_W // 2   # the nose cannon
+            # Bullet leaves row 5 (ship tip) and climbs; invader rows are 1 and 2.
+            hit = None
+            for row in (1, 0):  # lowest invader row first, the one a bullet meets first
+                travel = (5 - (row + 1)) / self.SHOT_SPEED
+                at = fired + travel
+                off = self._march(at, span)
+                i, rem = divmod(x - off, self.GAP)
+                if 0 <= i < self.COLS and rem < 3 and (row, i) not in dead:
+                    hit = (row, i, at)
+                    break
+            if hit and hit[2] <= t:
+                row, i, at = hit
+                dead.add((row, i))
+                score += 30 if row == 0 else 20
+                if t - at < 0.35:
+                    booms.append((row + 1, self._march(at, span) + i * self.GAP + 1, t - at))
+            else:
+                y = 5 - (t - fired) * self.SHOT_SPEED
+                end = (hit[0] + 1) if hit else -1
+                if y > end:
+                    bullets.append((int(y), x))
+        total_score = int(t / self.WAVE) * 400 + score
+        return self._march(t, span), dead, booms, bullets, total_score
+
+    def draw(self, grid, top: int, t: float, left: Optional[int] = None):
+        width = len(grid[0])
+        left, fw = self.field(width, left)
+        fw = min(fw, width - left)
+
+        def put(r, c, ch, style):
+            if 0 <= top + r < len(grid) and 0 <= left + c < min(width, left + fw):
+                grid[top + r][left + c] = (ch, style)
+
+        off, dead, booms, bullets, score = self.state(t, fw)
+        frame = int(t / self.STEP) % 2
+        for j, ch in enumerate(f"SCORE {score:05d}"):
+            put(0, j, ch, "#5fd787")
+        hi = "HI 09990"
+        for j, ch in enumerate(hi):
+            put(0, fw - len(hi) + j, ch, "#878787")
+        # Mothership crosses the top every so often (over the score, like the real thing).
+        ut = t % 9.0
+        if ut < 3.0:
+            ux = int((fw + len(UFO)) * ut / 3.0) - len(UFO)
+            for j, ch in enumerate(UFO):
+                put(0, ux + j, ch, "bold #ff5f5f" if ch == "●" and int(t * 8) % 2 else "#ff8787")
+        for row, (a, b, color) in enumerate(INVADERS):
+            sprite = a if frame == 0 else b
+            for i in range(self.COLS):
+                if (row, i) in dead:
+                    continue
+                for j, ch in enumerate(sprite):
+                    put(row + 1, off + i * self.GAP + j, ch, color)
+        for r, c, age in booms:
+            ch = "✶" if age < 0.12 else "✷" if age < 0.24 else "·"
+            for dc, g in ((-1, "╲"), (0, ch), (1, "╱")):
+                put(r, c + dc, g if age < 0.24 else " " if dc else ch, "bold #ffd75f")
+        for y, x in bullets:
+            if 0 <= y <= 5:
+                put(y, x, "│", "bold #ffffaf")
+        sx = int(round(self._ship_x(t, fw)))
+        flame = int(t * 10) % 3
+        name_row = next(i for i, r in enumerate(SHIP) if "H U B B L E" in r)
+        for r, line in enumerate(SHIP):
+            for j, ch in enumerate(line):
+                if ch == " " and r != name_row:
+                    continue
+                if ch == "▲":
+                    style = "bold #ffffff" if int(t * 6) % 2 else "bold #d7e7ff"
+                elif ch == "▼":
+                    ch = ("▼", "▽", "▾")[(flame + j) % 3]
+                    style = ("bold #ffd75f", "#ff8700", "#ff5f00")[(flame + j) % 3]
+                elif ch.isalpha():
+                    style = f"bold {_blend(GRADIENT, ((j / SHIP_W) + t * 0.15) % 1.0)}"  # glowing name
+                elif r == name_row and ch == " ":
+                    style = ""  # opaque inside the hull, so stars pass behind the ship
+                elif ch in "◢◣":
+                    style = "#ff5f87"  # wing-tip lights
+                else:
+                    style = "#afc7e7" if r < name_row else "#5f87af"
+                put(5 + r, sx + j, ch, style)
+
+
+ARCADE = _Arcade()
+
+
 # ----- composed home screen -------------------------------------------------
 
 _MEASURE = Console(width=400, color_system="truecolor", force_terminal=True, legacy_windows=False,
@@ -440,27 +591,25 @@ def compose_grid(width: int, height: int, t: float, status: List[Text], tips: Li
     """
     width = max(40, min(width - 1, 110))
     height = max(height, 1)
-    # Logo sizes: 2 = large pixel letters, 1 = block letters, 0 = one-line wordmark.
+    # Logo sizes: 1 = block letters, 0 = one-line wordmark. (2, the large pixel letters, is kept
+    # for anyone who wants it back, but the HUBBLE starship is the star of the screen now.)
     logo_h = {2: 9, 1: 7, 0: 1}  # letter rows + shadow row + tagline
-    top = 2 if width >= BIG_LOGO_WIDTH + 4 else (1 if width >= 58 else 0)
-    mid = min(top, 1)
-    # Richest to poorest. The name is the last thing to shrink: first drop the scene, then the
-    # tips, then status lines, and only then fall back to a smaller logo.
+    top = 1 if width >= 58 else 0
+    # Richest to poorest: the starship scene comes first, then the bigger logo, then tips,
+    # then status lines.
     n_status = len(status)
-    layouts = []
-    for cand_size in dict.fromkeys([top, mid, 0]):
-        for cand_art in (FULL, COMPACT, None):
-            layouts.append((cand_size, cand_art, True, n_status))
-        for cand_art in (COMPACT, None):
-            layouts.append((cand_size, cand_art, False, n_status))
-        for n in (min(2, n_status), min(1, n_status), 0):
-            layouts.append((cand_size, None, False, n))
+    shrink = [(True, n_status), (False, n_status), (False, min(2, n_status)), (False, min(1, n_status)),
+              (False, 0)]
+    layouts = [(s, a, tp, n) for a in (ARCADE, None) for s in dict.fromkeys([top, 0]) for tp, n in shrink]
     size, art, with_tips, n_status = layouts[-1]
+
+    def art_rows(a):
+        return a.height + 1 if a is not None else 0
+
     for cand_size, cand_art, cand_tips, cand_n in layouts:
-        if cand_art is not None and width < cand_art.width + 24:
+        if cand_art is ARCADE and width < ARCADE.width + 4:
             continue
-        need = logo_h[cand_size] + 1 + (cand_art.height + 1 if cand_art else 0) + cand_n + \
-            (1 + len(tips) if cand_tips else 0) + 1
+        need = logo_h[cand_size] + 1 + art_rows(cand_art) + cand_n + (1 + len(tips) if cand_tips else 0) + 1
         if need <= height:
             size, art, with_tips, n_status = cand_size, cand_art, cand_tips, cand_n
             break
@@ -468,7 +617,7 @@ def compose_grid(width: int, height: int, t: float, status: List[Text], tips: Li
     use_big = size > 0
     logo_h = logo_h[size]
 
-    rows_total = logo_h + 1 + (art.height + 1 if art else 0) + len(status) + (1 + len(tips) if with_tips else 0) + 1
+    rows_total = logo_h + 1 + art_rows(art) + len(status) + (1 + len(tips) if with_tips else 0) + 1
     rows_total = min(rows_total, height) if rows_total > height else rows_total  # never exceed the budget
     grid = _new_grid(width, max(rows_total, 1))
     _draw_stars(grid, t)
@@ -490,7 +639,10 @@ def compose_grid(width: int, height: int, t: float, status: List[Text], tips: Li
         _stamp_text(grid, row, 2, Text.assemble(small_logo(), ("  v" + version, "dim")))
     row += logo_h + 1
 
-    if art is not None:
+    if art is ARCADE:
+        ARCADE.draw(grid, row, t)
+        row += ARCADE.height + 1
+    elif isinstance(art, _Art):
         _draw_comet(grid, row, t)
         _draw_scene(grid, row, t, art)
         row += art.height + 1