asher-cli 0.0.2__tar.gz → 0.0.3__tar.gz

asher_cli-0.0.3/.env.example

@@ -0,0 +1,3 @@
+LITTER_ROBOT_USER=email
+LITTER_ROBOT_PASSWORD=password
+ASHER_CLI_DEV_MODE=true

{asher_cli-0.0.2 → asher_cli-0.0.3}/.githooks/pre-push

@@ -10,7 +10,4 @@ uv run ruff format --check .
 echo "► mypy"
 uv run mypy asher/ --ignore-missing-imports
 
-echo "► pytest"
-uv run pytest tests/ -v --tb=short
-
 echo "✓ all checks passed"

{asher_cli-0.0.2 → asher_cli-0.0.3}/.github/workflows/ci.yml

@@ -19,6 +19,7 @@ jobs:
       - run: uv run ruff format --check .
       - run: uv run mypy asher/ --ignore-missing-imports
 
+
   test:
     needs: lint
     strategy:

asher_cli-0.0.3/.github/workflows/claude-code-review.yml

@@ -0,0 +1,44 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    if: |
+      github.event.pull_request.user.login == 'external-contributor' ||
+      github.event.pull_request.user.login == 'new-developer' ||
+      github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
+          plugins: 'code-review@claude-code-plugins'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+

asher_cli-0.0.3/.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr *)'
+

asher_cli-0.0.3/.github/workflows/coverage.yml

@@ -0,0 +1,24 @@
+name: Coverage
+
+on:
+  schedule:
+    - cron: "0 6 * * *"  # daily at 06:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv sync --dev
+      - name: Run tests with coverage
+        run: uv run pytest tests/ --cov=asher --cov-report=lcov --cov-report=term-missing
+      - name: Upload to Coveralls
+        uses: coverallsapp/github-action@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          path-to-lcov: coverage.lcov

asher_cli-0.0.3/.github/workflows/dependency-audit.yml

@@ -0,0 +1,37 @@
+name: Dependency Audit
+
+on:
+  schedule:
+    - cron: "0 0 * * 1"  # every Monday at midnight UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  dependency-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv export --format requirements-txt > /tmp/requirements.txt
+      - name: Audit Python dependencies
+        uses: pypa/gh-action-pip-audit@v1.0.8
+        with:
+          inputs: /tmp/requirements.txt
+      - name: Upgrade lock file
+        run: uv lock --upgrade
+      - name: Open upgrade PR
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: "chore: weekly dependency upgrades"
+          title: "chore: weekly dependency upgrades"
+          body: |
+            Automated weekly dependency upgrade via `uv lock --upgrade`.
+
+            Upgrades packages to their latest versions within the constraints
+            defined in `pyproject.toml`. Review the lock file diff before merging.
+          branch: chore/weekly-dep-upgrades
+          delete-branch: true
+          add-paths: uv.lock

{asher_cli-0.0.2 → asher_cli-0.0.3}/CLAUDE.md

@@ -10,12 +10,22 @@ Terminal dashboard for Litter Robot (LR3/LR4/LR5) via the Whisker cloud API.
 - **python-dotenv** — credential loading (`.env` fallback)
 - **keyring>=24** — OS credential store (Windows Credential Manager / macOS Keychain / Linux Secret Service)
 
+## Tooling
+
+- **uv** — dependency management and task runner (`uv sync`, `uv run`)
+- **poethepoet** — task aliases via `uv run poe <task>`
+- **ruff** — linter and formatter
+- **mypy** — static type checking
+- **pytest + pytest-asyncio + pytest-cov** — tests
+- **textual-dev** — CSS hot reload devtools
+- **watchfiles** — Python auto-restart on file change
+
 ## Entry points
 
 ```
 python app.py          # compatibility shim (calls asher/__main__.py)
 python -m asher        # run as module
-asher                  # after: pip install -e .
+asher                  # after: uv sync && uv run asher  OR  pip install -e .
 ```
 
 ## Package structure
@@ -35,8 +45,16 @@ asher/
   slash-commands/   Convention doc + future slash-command registry
 
 tests/
-  conftest.py       shared fixtures (mock_robot, mock_account)
-  testhelpers.py    unit tests for helpers.py
+  testhelpers.py          unit tests for helpers.py
+  test_cats.py            CATS dict structure
+  test_auth.py            LoginScreen CSS / structure
+  test_auth_pilot.py      Textual Pilot integration tests for LoginScreen
+  test_app_pilot.py       Textual Pilot integration tests for AsherApp
+  test_commands_pilot.py  Textual Pilot integration tests for command dispatch
+  test_connection.py      keyring helper functions
+  test_connection_mixin.py ConnectionMixin structure
+  test_monitoring.py      MonitoringMixin async methods
+  test_ui.py              UIMixin constants, CSS, helper existence
 
 .github/workflows/
   ci.yml            ruff + mypy + pytest on every push/PR
@@ -52,8 +70,8 @@ Priority order on startup:
 
 `.env` variable names (for fallback):
 ```
-LITTER_ROBOT_USER=...      # or LR4_EMAIL
-LITTER_ROBOT_PASSWORD=...  # or LR4_PASSWORD
+LITTER_ROBOT_USER=...
+LITTER_ROBOT_PASSWORD=...
 ```
 
 Keyring service name: `asher-cli`, keys `email` and `password`.
@@ -132,6 +150,25 @@ pylitterbot auto-detects robot type. Any attribute/method missing on a given mod
 
 **Add a new cat state:** add entry to `CATS` dict in `asher/cats.py` (str for static, list[str] for animated), then call `_set_cat("name", "label")`.
 
-**Run tests:** `pytest tests/` (or `uv run pytest` if using uv).
-
 **File naming convention:** no underscores in filenames (except Python-required `__init__.py` and `__main__.py`).
+
+## Dev workflow
+
+```bash
+uv sync                  # install all deps (including dev group)
+uv run poe dev           # run with CSS hot reload (textual --dev)
+uv run poe watch         # run with Python auto-restart on file change (watchfiles)
+uv run poe test          # run test suite
+uv run poe check         # ruff + mypy + pytest (same as CI)
+uv run poe fix           # auto-fix ruff issues
+```
+
+Pre-push hook (`.githooks/pre-push`) runs: ruff check → ruff format --check → mypy. Tests are not in the hook — run them manually.
+
+## Testing notes
+
+- Pilot-based integration tests use `app.run_test()` with `await pilot.pause()` before querying widgets
+- Helper app wrappers for screens must **not** start with `Test` (pytest will try to collect them); use e.g. `LoginTestApp`
+- Mock external deps with `unittest.mock.AsyncMock` for async robot/account methods
+- `from pylitterbot import Account` is a local import inside `_connect_worker` — patch it at `pylitterbot.Account`, not `asher.connection.Account`
+- Coverage: ~76% overall; main gaps are async exception paths and `_connect_worker` auth flow

{asher_cli-0.0.2 → asher_cli-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asher-cli
-Version: 0.0.2
+Version: 0.0.3
 Summary: Terminal dashboard for Litter Robot (LR3/LR4/LR5) via the Whisker cloud API
 License: MIT License
         
@@ -43,6 +43,14 @@ Description-Content-Type: text/markdown
 
 # Asher CLI
 
+[![PyPI](https://img.shields.io/badge/PyPI-asher--cli-blue?logo=pypi&logoColor=white)](https://pypi.org/project/asher-cli/)
+![Version](https://img.shields.io/pypi/v/asher-cli?label=version)
+[![Python](https://img.shields.io/pypi/pyversions/asher-cli)](https://pypi.org/project/asher-cli/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![CI](https://github.com/karanshukla/asher-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/karanshukla/asher-cli/actions/workflows/ci.yml)
+[![Coverage Status](https://coveralls.io/repos/github/karanshukla/asher-cli/badge.svg?branch=main)](https://coveralls.io/github/karanshukla/asher-cli?branch=main)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
 A Claude Code-style terminal dashboard for monitoring and controlling Litter Robot via the Whisker cloud API.
 
 <img width="808" height="351" alt="image" src="https://github.com/user-attachments/assets/6599966f-837c-419c-8692-bfda3533e730" />
@@ -60,6 +68,8 @@ A Claude Code-style terminal dashboard for monitoring and controlling Litter Rob
 
 ## Install
 
+### With pipx (recommended)
+
 ```bash
 pipx install asher-cli
 asher
@@ -67,34 +77,27 @@ asher
 
 `pipx` installs the CLI into an isolated environment and puts `asher` on your PATH automatically. Install `pipx` with `pip install pipx` if you don't have it.
 
-Or with plain pip (ensure Python's `Scripts` folder is on your PATH):
+### With pip
 
 ```bash
 pip install asher-cli
 asher
 ```
 
-Or run from source:
+### With uv
 
 ```bash
-git clone https://github.com/karanshukla/asher-cli
-cd asher-cli
-pip install -e .
+uv tool install asher-cli
 asher
 ```
 
-### Dev setup
+### Run from source
 
 ```bash
-uv sync --dev
-git config core.hooksPath .githooks   # run lint + tests before every push
-```
-
-```bash
-uv run poe check   # ruff + mypy + pytest (same as CI)
-uv run poe fix     # auto-fix ruff issues
-uv run poe test    # tests only
-uv run poe types   # mypy only
+git clone https://github.com/karanshukla/asher-cli
+cd asher-cli
+uv sync
+uv run asher
 ```
 
 ## Credentials
@@ -179,10 +182,64 @@ python -m pip install pipx
 python -m pipx install asher-cli
 ```
 
-## Testing
+## Dev Setup
+
+### 1. Clone and install
+
+```bash
+git clone https://github.com/karanshukla/asher-cli
+cd asher-cli
+uv sync                                        # installs all deps including the dev group
+git config core.hooksPath .githooks            # lint + type checks run before every push
+```
+
+### 2. Configure environment (optional)
+
+Copy `.env.example` to `.env` and fill in your credentials:
+
+```bash
+cp .env.example .env
+```
+
+```env
+LITTER_ROBOT_USER=your@email.com
+LITTER_ROBOT_PASSWORD=yourpassword
+ASHER_CLI_DEV_MODE=true    # sets version to "dev" instead of the installed package version
+```
+
+### 3. Run with hot reload
+
+**CSS hot reload** — Textual's devtools watch inline `CSS` strings and `.tcss` files and reload them in-place without restarting:
+
+```bash
+uv run poe dev
+# equivalent to: textual run --dev asher/__main__.py
+```
+
+**Python auto-restart** — true in-process reload isn't possible with Textual's event loop, but `watchfiles` will kill and relaunch the app whenever a `.py` file changes in `asher/`:
 
 ```bash
-uv run pytest
+uv run poe watch
+# equivalent to: watchfiles --filter python 'python -m asher' asher
+```
+
+You can combine both — run `poe watch` for Python changes and it will naturally pick up CSS changes too on restart.
+
+### 4. Run tests
+
+```bash
+uv run poe test                  # run all tests
+uv run pytest tests/ --cov=asher # with coverage report
+```
+
+### 5. Lint, format, type-check
+
+```bash
+uv run poe fix     # auto-fix ruff issues
+uv run poe lint    # check only (no fixes)
+uv run poe fmt     # check formatting
+uv run poe types   # mypy
+uv run poe check   # run all of the above + tests (same as CI)
 ```
 
 CI runs on Python 3.10 / 3.11 / 3.12 across Ubuntu, Windows, and macOS on every push.

{asher_cli-0.0.2 → asher_cli-0.0.3}/README.md

@@ -1,5 +1,13 @@
 # Asher CLI
 
+[![PyPI](https://img.shields.io/badge/PyPI-asher--cli-blue?logo=pypi&logoColor=white)](https://pypi.org/project/asher-cli/)
+![Version](https://img.shields.io/pypi/v/asher-cli?label=version)
+[![Python](https://img.shields.io/pypi/pyversions/asher-cli)](https://pypi.org/project/asher-cli/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![CI](https://github.com/karanshukla/asher-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/karanshukla/asher-cli/actions/workflows/ci.yml)
+[![Coverage Status](https://coveralls.io/repos/github/karanshukla/asher-cli/badge.svg?branch=main)](https://coveralls.io/github/karanshukla/asher-cli?branch=main)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
 A Claude Code-style terminal dashboard for monitoring and controlling Litter Robot via the Whisker cloud API.
 
 <img width="808" height="351" alt="image" src="https://github.com/user-attachments/assets/6599966f-837c-419c-8692-bfda3533e730" />
@@ -17,6 +25,8 @@ A Claude Code-style terminal dashboard for monitoring and controlling Litter Rob
 
 ## Install
 
+### With pipx (recommended)
+
 ```bash
 pipx install asher-cli
 asher
@@ -24,34 +34,27 @@ asher
 
 `pipx` installs the CLI into an isolated environment and puts `asher` on your PATH automatically. Install `pipx` with `pip install pipx` if you don't have it.
 
-Or with plain pip (ensure Python's `Scripts` folder is on your PATH):
+### With pip
 
 ```bash
 pip install asher-cli
 asher
 ```
 
-Or run from source:
+### With uv
 
 ```bash
-git clone https://github.com/karanshukla/asher-cli
-cd asher-cli
-pip install -e .
+uv tool install asher-cli
 asher
 ```
 
-### Dev setup
+### Run from source
 
 ```bash
-uv sync --dev
-git config core.hooksPath .githooks   # run lint + tests before every push
-```
-
-```bash
-uv run poe check   # ruff + mypy + pytest (same as CI)
-uv run poe fix     # auto-fix ruff issues
-uv run poe test    # tests only
-uv run poe types   # mypy only
+git clone https://github.com/karanshukla/asher-cli
+cd asher-cli
+uv sync
+uv run asher
 ```
 
 ## Credentials
@@ -136,10 +139,64 @@ python -m pip install pipx
 python -m pipx install asher-cli
 ```
 
-## Testing
+## Dev Setup
+
+### 1. Clone and install
+
+```bash
+git clone https://github.com/karanshukla/asher-cli
+cd asher-cli
+uv sync                                        # installs all deps including the dev group
+git config core.hooksPath .githooks            # lint + type checks run before every push
+```
+
+### 2. Configure environment (optional)
+
+Copy `.env.example` to `.env` and fill in your credentials:
+
+```bash
+cp .env.example .env
+```
+
+```env
+LITTER_ROBOT_USER=your@email.com
+LITTER_ROBOT_PASSWORD=yourpassword
+ASHER_CLI_DEV_MODE=true    # sets version to "dev" instead of the installed package version
+```
+
+### 3. Run with hot reload
+
+**CSS hot reload** — Textual's devtools watch inline `CSS` strings and `.tcss` files and reload them in-place without restarting:
+
+```bash
+uv run poe dev
+# equivalent to: textual run --dev asher/__main__.py
+```
+
+**Python auto-restart** — true in-process reload isn't possible with Textual's event loop, but `watchfiles` will kill and relaunch the app whenever a `.py` file changes in `asher/`:
 
 ```bash
-uv run pytest
+uv run poe watch
+# equivalent to: watchfiles --filter python 'python -m asher' asher
+```
+
+You can combine both — run `poe watch` for Python changes and it will naturally pick up CSS changes too on restart.
+
+### 4. Run tests
+
+```bash
+uv run poe test                  # run all tests
+uv run pytest tests/ --cov=asher # with coverage report
+```
+
+### 5. Lint, format, type-check
+
+```bash
+uv run poe fix     # auto-fix ruff issues
+uv run poe lint    # check only (no fixes)
+uv run poe fmt     # check formatting
+uv run poe types   # mypy
+uv run poe check   # run all of the above + tests (same as CI)
 ```
 
 CI runs on Python 3.10 / 3.11 / 3.12 across Ubuntu, Windows, and macOS on every push.

{asher_cli-0.0.2 → asher_cli-0.0.3}/ROADMAP.md

@@ -1891,5 +1891,7 @@ Ranked by user-visible impact vs. implementation effort:
 22. **Desktop notifications** (§20) — `plyer` toasts + `winsound` bell on fault/cat-detected; `/notify on|off` command
 23. **Dark/light theme toggle** (§11) — CSS variable swap; nice-to-have but not critical
 24. **Startup animation** (§11) — cute but adds friction to quick status checks; could be opt-in
+25. **E2E test harness** (§15) — Textual Pilot tests for critical user flows; good for preventing regressions but requires maintenance
+26. **Refactor to be more clean code** - example: have a base command class, and have a property to determine whether its a slash command or not, instead of having two separate methods for slash and non-slash commands. This would reduce code duplication and make it easier to add new commands in the future.
 
 

{asher_cli-0.0.2 → asher_cli-0.0.3}/asher/app.py

@@ -17,7 +17,7 @@ from .ui import UIMixin
 
 
 class AsherApp(UIMixin, ConnectionMixin, MonitoringMixin, CommandsMixin, App):  # type: ignore[type-arg]
-    CSS = UIMixin.CSS  # type: ignore[misc]  # must live in AsherApp.__dict__ so Textual gives it full user-CSS priority
+    CSS_PATH = "ui/style.tcss"
     BINDINGS = [
         Binding("ctrl+c", "quit", "Quit", priority=True),
         Binding("ctrl+l", "clear_log", "Clear log"),
@@ -31,10 +31,12 @@ class AsherApp(UIMixin, ConnectionMixin, MonitoringMixin, CommandsMixin, App):
         self._pets: list = []
         self._cat_mode: str = "idle"
         self._cat_frame: int = 0
+        self._cat_fx_idx: int = 0
         self._cmd_history: list[str] = []
         self._hist_idx: int = -1
-        self._login_state: str = ""  # "" | "awaiting_email" | "awaiting_password"
-        self._login_email: str = ""
+        from .login_flow import LoginFlow
+
+        self._login = LoginFlow()
         self._last_cat_seen: Any = None
         self._is_loading: bool = True
         self._spinner_idx: int = 0
@@ -47,7 +49,7 @@ class AsherApp(UIMixin, ConnectionMixin, MonitoringMixin, CommandsMixin, App):
         self._show_loading_state()
         self._connect_worker()
         self.set_interval(30, self._poll_status_interval)
-        self.set_interval(0.9, self._tick_cat)
+        self.set_interval(0.4, self._tick_cat)
         # this doesn't work for some reason :(
         inp = self.query_one("#cmd-input", Input)
         inp.set_styles(self._INPUT_STYLES)
@@ -62,3 +64,4 @@ class AsherApp(UIMixin, ConnectionMixin, MonitoringMixin, CommandsMixin, App):
         if self._account:
             with contextlib.suppress(Exception):
                 await self._account.disconnect()
+        print("meow")

asher_cli-0.0.3/asher/cats.py

@@ -0,0 +1,93 @@
+"""ASCII cat art definitions."""
+
+from __future__ import annotations
+
+
+def _frame(eyes: str, extra: str = "") -> str:
+    """Build a single cat frame with the given eye expression and tail extra."""
+    e1, e2 = eyes[0], eyes[2]
+    line3 = "  \\" + e1 + " " + e2 + "/"
+    last = "\\_____/" + extra
+    return "\n".join(
+        [
+            " /\\___/\\",
+            " \\/   \\/",
+            line3,
+            " ==`^ ==",
+            "  /   \\",
+            " /|   |",
+            " || - |",
+            " ||   |",
+            " ||| ||_",
+            "/\\||_|//",
+            last,
+        ]
+    )
+
+
+# idle: slow blink cycle (6 frames)
+IDLE = [
+    _frame("o o"),  # 0 eyes open
+    _frame("o o"),  # 1
+    _frame("- -"),  # 2 closing
+    _frame("- -"),  # 3 closed
+    _frame("o o"),  # 4 opening
+    _frame("o o"),  # 5
+]
+
+# happy: eye squint cycle (6 frames)
+HAPPY = [
+    _frame("^ ^"),  # 0
+    _frame("^ ^"),  # 1
+    _frame("- -"),  # 2 squint
+    _frame("^ ^"),  # 3
+    _frame("^ ^"),  # 4
+    _frame("- -"),  # 5 squint
+]
+
+# sleeping: floating zZ (8 frames)
+SLEEPING = [
+    _frame("- -", " z"),  # 0
+    _frame("- -", "zZ"),  # 1
+    _frame("- -", " Z"),  # 2
+    _frame("- -", "zZ"),  # 3
+    _frame("- -", " z"),  # 4
+    _frame("- -", "zZ"),  # 5
+    _frame("- -", " Z"),  # 6
+    _frame("- -", "zZ"),  # 7
+]
+
+# cleaning: active cycle (6 frames)
+CLEANING = [
+    _frame("@ o"),  # 0
+    _frame("o @"),  # 1
+    _frame("* *"),  # 2
+    _frame("@ o"),  # 3
+    _frame("o @"),  # 4
+    _frame("* *"),  # 5
+]
+
+# error: alarm flash (4 frames)
+ERROR = [
+    _frame("x x"),  # 0
+    _frame("x x", "!"),  # 1 flash
+    _frame("x x"),  # 2
+    _frame("x x", "!"),  # 3 flash
+]
+
+# full: agitated eye flash (4 frames)
+FULL = [
+    _frame("! !"),  # 0
+    _frame("x !"),  # 1 agitated
+    _frame("! !"),  # 2
+    _frame("! x"),  # 3 agitated
+]
+
+CATS: dict[str, list[str]] = {
+    "idle": IDLE,
+    "happy": HAPPY,
+    "sleeping": SLEEPING,
+    "cleaning": CLEANING,
+    "error": ERROR,
+    "full": FULL,
+}