df

cli_renderers.py

@@ -0,0 +1,325 @@
+"""Shared renderers for typer-test output tables.
+
+This module centralizes Rich table rendering so typer-test.py stays lean. It includes
+specialized handling for planets plus generic list/dict/object renderers.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Sequence
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from tarot import Card
+from utils.attributes import Color, Planet
+
+
+class Renderer:
+    """Render arbitrary Tarot objects using Rich tables."""
+
+    def __init__(self, console: Console) -> None:
+        self.console = console
+        self.planet_renderer = PlanetRenderer(self)
+
+    # Public helpers -----------------------------------------------------
+    def render_value(self, value: Any) -> None:
+        if isinstance(value, Planet):
+            self.planet_renderer.render(value)
+            return
+        if isinstance(value, Card):
+            self._render_card(value)
+            return
+        if isinstance(value, list) and value and isinstance(value[0], Card):
+            self.print_cards_table(value)
+            return
+        if hasattr(value, "upright") and hasattr(value, "reversed"):
+            self.print_kv_table(
+                "Meaning", {"upright": value.upright, "reversed": value.reversed}
+            )
+            return
+        if isinstance(value, dict):
+            self._render_dict(value)
+            return
+        if isinstance(value, list):
+            self._render_list(value)
+            return
+        if hasattr(value, "__dict__"):
+            self._render_object(value)
+            return
+        self.console.print(value)
+
+    def print_kv_table(self, title: str, data: Dict[str, Any]) -> None:
+        table = Table(title=title, show_header=False)
+        table.add_column("Field", style="bold")
+        table.add_column("Value")
+        for key, value in data.items():
+            table.add_row(self._humanize_key(str(key)), "" if value is None else str(value))
+        self.console.print(table)
+
+    def print_rows_table(self, title: str, columns: List[str], rows: List[List[Any]]) -> None:
+        table = Table(title=title, show_header=True, show_lines=True)
+        for col in columns:
+            table.add_column(col)
+        for row in rows:
+            str_row = ["" if v is None else str(v) for v in row]
+            table.add_row(*str_row)
+        self.console.print(table)
+
+    def print_cards_table(self, cards: List[Card]) -> None:
+        table = Table(title="Cards", show_lines=True)
+        table.add_column("#", justify="right")
+        table.add_column("Name")
+        table.add_column("Arcana")
+        table.add_column("Suit")
+        table.add_column("Pip/Court")
+
+        for card in cards:
+            suit = getattr(getattr(card, "suit", None), "name", "")
+            pip = str(getattr(card, "pip", "")) if getattr(card, "pip", None) else ""
+            court = getattr(card, "court_rank", "")
+            pip_display = court or pip
+            table.add_row(
+                str(getattr(card, "number", "")),
+                getattr(card, "name", ""),
+                getattr(card, "arcana", ""),
+                suit,
+                pip_display,
+            )
+
+        self.console.print(table)
+
+    # Internal renderers -------------------------------------------------
+    def _render_card(self, card: Card) -> None:
+        suit = getattr(card, "suit", None)
+        lines: List[str] = [f"Arcana: {card.arcana}"]
+        if suit is not None and getattr(suit, "name", None):
+            lines.append(f"Suit: {suit.name}")
+        if getattr(card, "pip", 0):
+            lines.append(f"Pip: {card.pip}")
+        if getattr(card, "court_rank", ""):
+            lines.append(f"Court Rank: {card.court_rank}")
+        meaning = getattr(card, "meaning", None)
+        if meaning is not None:
+            if getattr(meaning, "upright", None):
+                lines.append(f"Upright: {meaning.upright}")
+            if getattr(meaning, "reversed", None):
+                lines.append(f"Reversed: {meaning.reversed}")
+        keywords = getattr(card, "keywords", None)
+        if keywords:
+            lines.append(f"Keywords: {', '.join(keywords)}")
+        reversed_keywords = getattr(card, "reversed_keywords", None)
+        if reversed_keywords:
+            lines.append(f"Reversed Keywords: {', '.join(reversed_keywords)}")
+        guidance = getattr(card, "guidance", None)
+        if guidance:
+            lines.append(f"Guidance: {guidance}")
+        self.console.print(
+            Panel("\n".join(lines), title=f"{card.number}: {card.name}", expand=False)
+        )
+
+    def _render_object(self, obj: Any) -> None:
+        attrs = {k: v for k, v in vars(obj).items() if not k.startswith("_")}
+        display = {k: self._format_value(v) for k, v in attrs.items()}
+        title = getattr(obj, "name", None) or obj.__class__.__name__
+        self.print_kv_table(str(title), display)
+
+    def _render_dict(self, data: Dict[Any, Any], title: str = "Result") -> None:
+        if not data:
+            self.console.print(f"{title}: {{}}")
+            return
+
+        values = list(data.values())
+
+        if all(self._is_scalar(v) for v in values):
+            self.print_kv_table(title, data)
+            return
+
+        if all(isinstance(v, list) for v in values) and values and values[0]:
+            first_item = values[0][0]
+            if hasattr(first_item, "__dict__"):
+                self._render_dict_of_list_objects(data, title)
+                return
+
+        if all(hasattr(v, "__dict__") for v in values):
+            rows = []
+            sample_attrs = self._simple_attrs(values[0])
+            columns = ["Key"] + [self._humanize_key(k) for k in sample_attrs.keys()]
+            for key, obj in data.items():
+                attrs = self._simple_attrs(obj)
+                rows.append([key] + [attrs.get(k, "") for k in sample_attrs.keys()])
+            self.print_rows_table(title, columns, rows)
+            return
+
+        self.print_kv_table(title, {k: self._short_value(v) for k, v in data.items()})
+
+    def _render_list(self, items: List[Any], title: str = "Result") -> None:
+        if not items:
+            self.console.print(f"{title}: []")
+            return
+
+        first = items[0]
+
+        if isinstance(first, Card):
+            self.print_cards_table(items)
+            return
+
+        if hasattr(first, "__dict__"):
+            sample_attrs = self._simple_attrs(first)
+            columns = [self._humanize_key(k) for k in sample_attrs.keys()]
+            rows = []
+            for obj in items:
+                attrs = self._simple_attrs(obj)
+                rows.append([attrs.get(k, "") for k in sample_attrs.keys()])
+            self.print_rows_table(title, columns, rows)
+            return
+
+        if isinstance(first, dict):
+            keys = list(first.keys())
+            columns = [self._humanize_key(k) for k in keys]
+            rows = []
+            for obj in items:
+                rows.append([obj.get(k, "") for k in keys])
+            self.print_rows_table(title, columns, rows)
+            return
+
+        self.print_kv_table(title, {i: self._short_value(v) for i, v in enumerate(items)})
+
+    def _render_dict_of_list_objects(self, data: Dict[Any, List[Any]], title: str) -> None:
+        first_key = next(iter(data))
+        first_list = data[first_key]
+        if not first_list:
+            self.print_kv_table(title, {k: "[]" for k in data.keys()})
+            return
+        sample_attrs = self._simple_attrs(first_list[0])
+        columns = ["Key"] + [self._humanize_key(k) for k in sample_attrs.keys()]
+        rows: List[List[Any]] = []
+        for key, lst in data.items():
+            for obj in lst:
+                attrs = self._simple_attrs(obj)
+                rows.append([key] + [attrs.get(k, "") for k in sample_attrs.keys()])
+        self.print_rows_table(title, columns, rows)
+
+    # Value helpers ------------------------------------------------------
+    @staticmethod
+    def _simple_attrs(obj: Any) -> Dict[str, Any]:
+        return {k: v for k, v in vars(obj).items() if not k.startswith("_")}
+
+    @staticmethod
+    def _is_scalar(val: Any) -> bool:
+        return isinstance(val, (str, int, float, bool)) or val is None
+
+    def _format_value(self, val: Any, depth: int = 0) -> str:
+        if isinstance(val, list):
+            if not val:
+                return "[]"
+            lines = []
+            for item in val:
+                lines.append("  " * depth + "- " + self._format_value(item, depth + 1).lstrip())
+            return "\n".join(lines)
+        if isinstance(val, dict):
+            lines = []
+            for k, v in val.items():
+                lines.append(
+                    "  " * depth
+                    + f"{self._humanize_key(str(k))}: "
+                    + self._format_value(v, depth + 1)
+                )
+            return "\n".join(lines)
+        if hasattr(val, "__dict__"):
+            inner = {k: v for k, v in vars(val).items() if not k.startswith("_")}
+            if not inner:
+                return str(val)
+            parts = [
+                f"{self._humanize_key(str(k))}={self._short_value(v)}" for k, v in inner.items()
+            ]
+            name = getattr(val, "name", val.__class__.__name__)
+            return f"{name}: " + "; ".join(parts)
+        return str(val)
+
+    def _short_value(self, val: Any) -> str:
+        if isinstance(val, Card):
+            return f"Card {getattr(val, 'number', '?')}: {getattr(val, 'name', '')}"
+        if isinstance(val, list):
+            if not val:
+                return "[]"
+            preview = ", ".join(self._short_value(v) for v in val[:4])
+            suffix = "..." if len(val) > 4 else ""
+            return f"[{preview}{suffix}]"
+        if isinstance(val, dict):
+            return f"dict({len(val)})"
+        return str(val)
+
+    @staticmethod
+    def _humanize_key(key: str) -> str:
+        return key.replace("_", " ")
+
+
+class PlanetRenderer:
+    """Type-specific table rendering for planets."""
+
+    def __init__(self, renderer: Renderer) -> None:
+        self.renderer = renderer
+
+    @property
+    def console(self) -> Console:
+        return self.renderer.console
+
+    def render(self, planet: Planet) -> None:
+        base_fields = {
+            "Symbol": planet.symbol,
+            "Element": planet.element,
+            "Ruling Zodiac": self._join_list(planet.ruling_zodiac),
+            "Associated Letters": self._join_list(planet.associated_letters),
+            "Keywords": self._join_list(planet.keywords),
+            "Description": planet.description,
+        }
+        self.renderer.print_kv_table(f"Planet: {planet.name}", self._compact(base_fields))
+
+        if planet.associated_numbers:
+            rows = []
+            for number in planet.associated_numbers:
+                color_label = self._color_label(number.color)
+                rows.append(
+                    [
+                        getattr(number, "value", ""),
+                        getattr(number, "sephera", ""),
+                        getattr(number, "element", ""),
+                        getattr(number, "compliment", ""),
+                        color_label,
+                    ]
+                )
+            self.renderer.print_rows_table(
+                "Associated Numbers",
+                ["Value", "Sephera", "Element", "Compliment", "Color"],
+                rows,
+            )
+
+        if planet.color:
+            color = planet.color
+            color_fields = {
+                "Name": color.name,
+                "Hex": color.hex_value,
+                "Element": color.element,
+                "Scale": color.scale,
+                "Meaning": color.meaning,
+                "Tarot Associations": self._join_list(getattr(color, "tarot_associations", [])),
+                "Description": color.description,
+            }
+            self.renderer.print_kv_table("Planetary Color", self._compact(color_fields))
+
+    @staticmethod
+    def _join_list(items: Sequence[Any]) -> str:
+        return ", ".join(str(item) for item in items) if items else ""
+
+    @staticmethod
+    def _compact(data: Dict[str, Any]) -> Dict[str, Any]:
+        return {k: v for k, v in data.items() if v not in (None, "", [], {})}
+
+    @staticmethod
+    def _color_label(color: Optional[Color]) -> str:
+        if isinstance(color, Color):
+            hex_part = f" ({color.hex_value})" if getattr(color, "hex_value", "") else ""
+            return f"{color.name}{hex_part}"
+        return ""

debug_paths.py

@@ -0,0 +1,27 @@
+from tarot.tarot_api import Tarot
+
+print("Initializing Tarot...")
+# Force initialization
+Tarot._ensure_initialized()
+Tarot.tree._ensure_initialized()
+
+print("Checking Paths...")
+paths = Tarot.tree.path()
+print(f"Found {len(paths)} paths")
+
+found_aleph = False
+for p in paths.values():
+    print(f"Path {p.number}: {p.hebrew_letter} -> {p.tarot_trump}")
+    if p.hebrew_letter == "Aleph":
+        found_aleph = True
+
+if not found_aleph:
+    print("Aleph path not found!")
+else:
+    print("Aleph path found.")
+
+print("Checking Cards...")
+cards = Tarot.deck.card.filter()
+print(f"Found {len(cards)} cards")
+fool = Tarot.deck.card.filter(name="Fool")
+print(f"Fool card: {fool}")

mytest.py

@@ -3,54 +3,12 @@ from temporal import ThalemaClock
 from datetime import datetime
 from utils import Personality, MBTIType
 
-# Tarot core functionality
+from tarot.ui import display_cards,display_cube
-card = Tarot.deck.card(3)
+from tarot.deck import Deck
-print(f"Card: {card}")
 
-# Spreads - now under Tarot.deck.card.spread()
+# Get some cards
-print("\n" + Tarot.deck.card.spread("Celtic Cross"))
+deck = Deck()
+cards = Tarot.deck.card.filter(suit="cups",type="ace")
 
-# Temporal functionality (separate module)
+print(cards)
-clock = ThalemaClock(datetime.now())
+# Display using default deck
-print(f"\nClock: {clock}")
-print(Tarot.deck.card.filter(suit="Cups"))
-
-# Top-level namespaces with pretty printing
-print("\n" + "=" * 60)
-print("Letter Namespace:")
-print(letter)
-
-print("\n" + "=" * 60)
-print("Number Namespace:")
-print(number)
-
-print("\nDigital root of 343:", number.digital_root(343))
-
-print("\n" + "=" * 60)
-print("Kaballah - Tree of Life:")
-print(kaballah.Tree)
-
-print("\n" + "=" * 60)
-print("Kaballah - Cube of Space:")
-print(kaballah.Cube.wall.display_filter(side="Below"))
-
-# Filtering examples
-print("\n" + "=" * 60)
-
-print(Tarot.deck.card.filter(type='court'))
-
-# MBTI Personality types mapped to Tarot court cards (1-to-1 direct mapping)
-print("\n" + "=" * 60)
-print("MBTI Personality Types & Tarot Court Cards")
-print("=" * 60)
-
-# Create personalities for all 16 MBTI types
-mbti_types = ['ENFP', 'ISTJ', 'INTJ', 'INFJ', 'ENTJ', 'ESFJ', 'ESTP', 'ISFJ',
-              'ENTP', 'ISFP', 'INTP', 'INFP', 'ESTJ', 'ESFP', 'ISTP', 'INTJ']
-for mbti in mbti_types:
-    personality = Personality.from_mbti(mbti, Tarot.deck)
-    print(f"\n{personality}")
-#prints court cards
-print(Tarot.deck.card.filter(suit="cups,wands"))
-
- 

pyproject.toml

@@ -28,6 +28,11 @@ classifiers = [
 dependencies = [
     "tomli>=1.2.0;python_version<'3.11'",
     "tomli_w>=1.0.0",
+    "Pillow>=9.0.0",
+    "typer>=0.12.5",
+    "rich>=10.11.0",
+    "shellingham>=1.3.0",
+    "prompt-toolkit>=3.0.47",
 ]
 
 [project.optional-dependencies]

src/tarot/card/card.py

@@ -292,7 +292,7 @@ class CardAccessor:
         """Return a nice representation of the deck accessor."""
         return self.__str__()
     
-    def spread(self, spread_name: str) -> str:
+    def spread(self, spread_name: str):
         """
         Draw a Tarot card reading for a spread.
         
@@ -304,7 +304,7 @@ class CardAccessor:
                         Examples: 'Celtic Cross', 'golden dawn', 'three_card', 'tree of life'
         
         Returns:
-            Formatted string with spread positions, drawn cards, and interpretations
+            SpreadReading object containing the spread and drawn cards
         
         Raises:
             ValueError: If spread name not found
@@ -328,4 +328,4 @@ class CardAccessor:
         
         # Create and return reading
         reading = SpreadReading(spread, drawn_cards)
-        return str(reading)
+        return reading

src/tarot/card/loader.py

@@ -206,7 +206,18 @@ def print_card_details(card: 'Card', include_reversed: bool = False) -> None:
         if hasattr(card, attr_name):
             value = getattr(card, attr_name)
             if value:
-                print(f"\n{display_name}:\n{value}")
+                if attr_name == 'explanation' and isinstance(value, dict):
+                    print(f"\n{display_name}:")
+                    if "summary" in value:
+                        print(f"Summary: {value['summary']}")
+                    if "waite" in value:
+                        print(f"Waite: {value['waite']}")
+                    # Print other keys if any
+                    for k, v in value.items():
+                        if k not in ["summary", "waite"]:
+                            print(f"{k.capitalize()}: {v}")
+                else:
+                    print(f"\n{display_name}:\n{value}")
     
     # Print list attributes
     for attr_name, display_info in list_attributes.items():

src/tarot/constants.py

@@ -0,0 +1,163 @@
+"""Shared constants and helpers for Tarot deck structure and ordering.
+
+This module centralizes deck ordering, pip naming, and position mapping
+so other modules can stay DRY and rely on a single source of truth.
+"""
+
+from typing import Dict, List, Tuple
+
+ACE_NAME = "Ace"
+
+# Minor sequencing and naming
+# Ace is its own category (container for the suit), pips are 2-10, then face cards
+PIP_ORDER: List[int] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
+
+# Numeric pip names only (2-10). Ace is intentionally excluded because it is not a pip card.
+PIP_NAMES: Dict[int, str] = {
+    2: "Two",
+    3: "Three",
+    4: "Four",
+    5: "Five",
+    6: "Six",
+    7: "Seven",
+    8: "Eight",
+    9: "Nine",
+    10: "Ten",
+}
+
+# Full minor rank names (Ace, 2-10, then courts)
+MINOR_RANK_NAMES: Dict[int, str] = {
+    1: ACE_NAME,
+    **PIP_NAMES,
+    11: "Prince",
+    12: "Knight",
+    13: "Princess",
+    14: "Queen",
+}
+
+# Map pip-order indices to actual pip numbers (1 maps to Ace, 2-10 are pip cards)
+PIP_INDEX_TO_NUMBER: Dict[int, int] = {
+    1: 1,
+    2: 2,
+    3: 3,
+    4: 4,
+    5: 5,
+    6: 6,
+    7: 7,
+    8: 8,
+    9: 9,
+    10: 10,
+}
+
+COURT_RANKS: Dict[int, str] = {
+    11: "Prince",
+    12: "Knight",
+    13: "Princess",
+    14: "Queen",
+}
+
+# Suit sequencing for the deck (number matches Suit.number)
+SUITS_FIRST: List[Tuple[str, str, int]] = [
+    ("Cups", "Water", 2),
+    ("Pentacles", "Earth", 4),
+    ("Swords", "Air", 3),
+]
+SUITS_LAST: List[Tuple[str, str, int]] = [
+    ("Wands", "Fire", 1),
+]
+
+MAJOR_ARCANA_NAMES: List[str] = [
+    "Fool",
+    "Magus",
+    "Fortune",
+    "Lust",
+    "Hanged Man",
+    "Death",
+    "Art",
+    "Devil",
+    "Tower",
+    "Star",
+    "Moon",
+    "Sun",
+    "High Priestess",
+    "Empress",
+    "Emperor",
+    "Hierophant",
+    "Lovers",
+    "Chariot",
+    "Justice",
+    "Hermit",
+    "Aeon",
+    "Universe",
+]
+
+MAJOR_ARCANA_KEYS: List[str] = [
+    "o",
+    "I",
+    "II",
+    "III",
+    "IV",
+    "V",
+    "VI",
+    "VII",
+    "VIII",
+    "IX",
+    "X",
+    "XI",
+    "XII",
+    "XIII",
+    "XIV",
+    "XV",
+    "XVI",
+    "XVII",
+    "XVIII",
+    "XIX",
+    "XX",
+    "XXI",
+]
+
+
+def minor_card_names_for_suit(suit_name: str) -> List[str]:
+    """Return the ordered card names for a minor suit using the shared rank order."""
+    return [f"{MINOR_RANK_NAMES[pip_index]} of {suit_name}" for pip_index in PIP_ORDER]
+
+
+def build_position_map() -> Dict[int, str]:
+    """Build the position map (1-78) aligned to deck ordering."""
+    position_map: Dict[int, str] = {}
+    pos = 1
+
+    # Cups, Pentacles, Swords (1-42)
+    for suit_name, _, _ in SUITS_FIRST:
+        for name in minor_card_names_for_suit(suit_name):
+            position_map[pos] = name
+            pos += 1
+
+    # Major Arcana (43-64)
+    for key in MAJOR_ARCANA_KEYS:
+        position_map[pos] = key
+        pos += 1
+
+    # Wands (65-78)
+    for suit_name, _, _ in SUITS_LAST:
+        for name in minor_card_names_for_suit(suit_name):
+            position_map[pos] = name
+            pos += 1
+
+    return position_map
+
+
+__all__ = [
+    "ACE_NAME",
+    "PIP_ORDER",
+    "PIP_NAMES",
+    "MINOR_RANK_NAMES",
+    "PIP_INDEX_TO_NUMBER",
+    "COURT_RANKS",
+    "SUITS_FIRST",
+    "SUITS_LAST",
+    "MAJOR_ARCANA_NAMES",
+    "MAJOR_ARCANA_KEYS",
+    "minor_card_names_for_suit",
+    "build_position_map",
+]

src/tarot/deck/deck.py

@@ -6,13 +6,22 @@ MajorCard, and MinorCard classes for representing individual cards.
 """
 
 from dataclasses import dataclass, field
-from typing import List, Optional, Tuple, TYPE_CHECKING
+from typing import List, Optional, Tuple, TYPE_CHECKING, Dict
 import random
 
 from ..attributes import (
     Meaning, CardImage, Suit, Zodiac, Element, Path,
     Planet, Sephera, Color, PeriodicTable, ElementType, DoublLetterTrump
 )
+from ..constants import (
+    COURT_RANKS,
+    MAJOR_ARCANA_NAMES,
+    PIP_INDEX_TO_NUMBER,
+    MINOR_RANK_NAMES,
+    PIP_ORDER,
+    SUITS_FIRST,
+    SUITS_LAST,
+)
 
 if TYPE_CHECKING:
     from ..card.data import CardDataLoader
@@ -44,7 +53,7 @@ class Card:
     pip: int = 0
     
     # Card-specific details
-    explanation: str = ""
+    explanation: Dict[str, str] = field(default_factory=dict)
     interpretation: str = ""
     keywords: List[str] = field(default_factory=list)
     reversed_keywords: List[str] = field(default_factory=list)
@@ -455,8 +464,10 @@ class Deck:
     def _initialize_deck(self) -> None:
         """Initialize the deck with all 78 Tarot cards.
         
-        Order: Cups (1-14), Pentacles/Disks (15-28), Swords (29-42), 
+         Order: Cups (1-14), Pentacles/Disks (15-28), Swords (29-42),
-               Major Arcana (43-64), Wands (65-78)
+             Major Arcana (43-64), Wands (65-78)
+
+         Minor suit sequencing (per suit): Ace, 2-10, Prince, Knight, Princess, Queen.
         
         This puts Queen of Wands as card #78, the final card.
         """
@@ -488,100 +499,41 @@ class Deck:
             "Princess": (earth_element, he_path),
             "Queen": (water_element, he_path),
         }
-        
+
-        suits_data_first = [
+        element_lookup = {
-            ("Cups", water_element, 2),
+            "Water": water_element,
-            ("Pentacles", earth_element, 4),
+            "Earth": earth_element,
-            ("Swords", air_element, 3),
+            "Air": air_element,
-        ]
+            "Fire": fire_element,
-        
-        # Pip order: Ace (1), Ten (10), Two-Nine (2-9), Knight (12), Prince (11), Princess (13), Queen (14)
-        pip_order = [1, 10, 2, 3, 4, 5, 6, 7, 8, 9, 12, 11, 13, 14]
-        pip_names = {
-            1: "Ace", 2: "Two", 3: "Three", 4: "Four", 5: "Five",
-            6: "Six", 7: "Seven", 8: "Eight", 9: "Nine", 10: "Ten",
-            11: "Prince", 12: "Knight", 13: "Princess", 14: "Queen"
         }
-        
+
+        def _suit_specs(suit_defs: List[Tuple[str, str, int]]) -> List[Tuple[str, ElementType, int]]:
+            specs: List[Tuple[str, ElementType, int]] = []
+            for suit_name, element_key, suit_num in suit_defs:
+                element_obj = element_lookup.get(element_key)
+                if element_obj is None:
+                    raise RuntimeError(f"Failed to resolve element '{element_key}' for suit '{suit_name}'")
+                specs.append((suit_name, element_obj, suit_num))
+            return specs
+
+        suits_data_first = _suit_specs(SUITS_FIRST)
+        suits_data_last = _suit_specs(SUITS_LAST)
+
         card_number = 1
-        # Pip order: Ace (1), Ten (10), Two-Nine (2-9), then Court cards Knight (12), Prince (11), Princess (13), Queen (14)
+
-        # Map pip_order indices to actual pip numbers (1-10 only for pips)
-        pip_index_to_number = {
-            1: 1,      # Ace
-            10: 10,    # Ten
-            2: 2, 3: 3, 4: 4, 5: 5, 6: 6, 7: 7, 8: 8, 9: 9  # Two through Nine
-        }
-        court_ranks = {
-            12: "Knight", 11: "Prince", 13: "Princess", 14: "Queen"
-        }
-        
         # Loop through first three suits
-        for suit_name, element_name, suit_num in suits_data_first:
+        for suit_name, element_obj, suit_num in suits_data_first:
-            suit = Suit(name=suit_name, element=element_name, 
+            card_number = self._add_minor_cards_for_suit(
-                       tarot_correspondence=f"{suit_name} Suit", number=suit_num)
+                suit_name,
-            
+                element_obj,
-            # Then loop through each position in the custom order
+                suit_num,
-            for pip_index in pip_order:
+                card_number,
-                # Create appropriate card type based on pip_index
+                court_rank_mappings,
-                if pip_index <= 10:
+            )
-                    # Pip card (Ace through 10)
-                    actual_pip = pip_index_to_number[pip_index]
-                    if pip_index == 1:
-                        # Ace card
-                        card = AceCard(
-                            number=card_number,
-                            name=f"{pip_names[pip_index]} of {suit_name}",
-                            meaning=Meaning(
-                                upright=f"{pip_names[pip_index]} of {suit_name} upright",
-                                reversed=f"{pip_names[pip_index]} of {suit_name} reversed"
-                            ),
-                            arcana="Minor",
-                            suit=suit,
-                            pip=actual_pip
-                        )
-                    else:
-                        # Regular pip card (2-10)
-                        card = PipCard(
-                            number=card_number,
-                            name=f"{pip_names[pip_index]} of {suit_name}",
-                            meaning=Meaning(
-                                upright=f"{pip_names[pip_index]} of {suit_name} upright",
-                                reversed=f"{pip_names[pip_index]} of {suit_name} reversed"
-                            ),
-                            arcana="Minor",
-                            suit=suit,
-                            pip=actual_pip
-                        )
-                else:
-                    # Court card (no pip)
-                    court_rank = court_ranks[pip_index]
-                    associated_element, hebrew_letter_path = court_rank_mappings[court_rank]
-                    card = CourtCard(
-                        number=card_number,
-                        name=f"{pip_names[pip_index]} of {suit_name}",
-                        meaning=Meaning(
-                            upright=f"{pip_names[pip_index]} of {suit_name} upright",
-                            reversed=f"{pip_names[pip_index]} of {suit_name} reversed"
-                        ),
-                        arcana="Minor",
-                        suit=suit,
-                        court_rank=court_rank,
-                        associated_element=associated_element,
-                        hebrew_letter_path=hebrew_letter_path
-                    )
-                self.cards.append(card)
-                card_number += 1
         
         # Major Arcana (43-64)
         # Names match filenames in src/tarot/deck/default/
-        major_arcana_names = [
+        for i, name in enumerate(MAJOR_ARCANA_NAMES):
-            "Fool", "Magus", "Fortune", "Lust", "Hanged Man", "Death",
-            "Art", "Devil", "Tower", "Star", "Moon", "Sun",
-            "High Priestess", "Empress", "Emperor", "Hierophant",
-            "Lovers", "Chariot", "Justice", "Hermit", "Aeon", "Universe"
-        ]
-        
-        for i, name in enumerate(major_arcana_names):
             card = MajorCard(
                 number=card_number,
                 name=name,
@@ -596,67 +548,82 @@ class Deck:
             card_number += 1
         
         # Minor Arcana - Last suit (Wands, 65-78)
-        # Organized logically: Ace, 10, 2-9, then court cards Knight, Prince, Princess, Queen
+        # Organized logically: Ace, 2-10, then court cards Prince, Knight, Princess, Queen
-        suits_data_last = [
+        for suit_name, element_obj, suit_num in suits_data_last:
-            ("Wands", fire_element, 1),
+            card_number = self._add_minor_cards_for_suit(
-        ]
+                suit_name,
+                element_obj,
+                suit_num,
+                card_number,
+                court_rank_mappings,
+            )
         
-        # Loop through last suit
+        # Load detailed explanations and keywords from registry
-        for suit_name, element_name, suit_num in suits_data_last:
+        try:
-            suit = Suit(name=suit_name, element=element_name, 
+            from ..card.loader import load_deck_details
-                       tarot_correspondence=f"{suit_name} Suit", number=suit_num)
+            load_deck_details(self)
-            
+        except ImportError:
-            # Then loop through each position in the custom order
+            # Handle case where loader might not be available or circular import issues
-            for pip_index in pip_order:
+            pass
-                # Create appropriate card type based on pip_index
+
-                if pip_index <= 10:
+
-                    # Pip card (Ace through 10)
+    def _add_minor_cards_for_suit(
-                    actual_pip = pip_index_to_number[pip_index]
+        self,
-                    if pip_index == 1:
+        suit_name: str,
-                        # Ace card
+        element_obj: ElementType,
-                        card = AceCard(
+        suit_num: int,
-                            number=card_number,
+        card_number: int,
-                            name=f"{pip_names[pip_index]} of {suit_name}",
+        court_rank_mappings: Dict[str, Tuple[ElementType, Path]],
-                            meaning=Meaning(
+    ) -> int:
-                                upright=f"{pip_names[pip_index]} of {suit_name} upright",
+        """Add all minor cards for a suit using shared ordering constants."""
-                                reversed=f"{pip_names[pip_index]} of {suit_name} reversed"
+        suit = Suit(
-                            ),
+            name=suit_name,
-                            arcana="Minor",
+            element=element_obj,
-                            suit=suit,
+            tarot_correspondence=f"{suit_name} Suit",
-                            pip=actual_pip
+            number=suit_num,
-                        )
+        )
-                    else:
+
-                        # Regular pip card (2-10)
+        for pip_index in PIP_ORDER:
-                        card = PipCard(
+            if pip_index <= 10:
-                            number=card_number,
+                actual_pip = PIP_INDEX_TO_NUMBER[pip_index]
-                            name=f"{pip_names[pip_index]} of {suit_name}",
+                name = f"{MINOR_RANK_NAMES[pip_index]} of {suit_name}"
-                            meaning=Meaning(
+                card_kwargs = {
-                                upright=f"{pip_names[pip_index]} of {suit_name} upright",
+                    "number": card_number,
-                                reversed=f"{pip_names[pip_index]} of {suit_name} reversed"
+                    "name": name,
-                            ),
+                    "meaning": Meaning(
-                            arcana="Minor",
+                        upright=f"{name} upright",
-                            suit=suit,
+                        reversed=f"{name} reversed",
-                            pip=actual_pip
+                    ),
-                        )
+                    "arcana": "Minor",
+                    "suit": suit,
+                    "pip": actual_pip,
+                }
+                if pip_index == 1:
+                    card = AceCard(**card_kwargs)
                 else:
-                    # Court card (no pip)
+                    card = PipCard(**card_kwargs)
-                    court_rank = court_ranks[pip_index]
+            else:
-                    associated_element, hebrew_letter_path = court_rank_mappings[court_rank]
+                court_rank = COURT_RANKS[pip_index]
-                    card = CourtCard(
+                associated_element, hebrew_letter_path = court_rank_mappings[court_rank]
-                        number=card_number,
+                name = f"{MINOR_RANK_NAMES[pip_index]} of {suit_name}"
-                        name=f"{pip_names[pip_index]} of {suit_name}",
+                card = CourtCard(
-                        meaning=Meaning(
+                    number=card_number,
-                            upright=f"{pip_names[pip_index]} of {suit_name} upright",
+                    name=name,
-                            reversed=f"{pip_names[pip_index]} of {suit_name} reversed"
+                    meaning=Meaning(
-                        ),
+                        upright=f"{name} upright",
-                        arcana="Minor",
+                        reversed=f"{name} reversed",
-                        suit=suit,
+                    ),
-                        court_rank=court_rank,
+                    arcana="Minor",
-                        associated_element=associated_element,
+                    suit=suit,
-                        hebrew_letter_path=hebrew_letter_path
+                    court_rank=court_rank,
-                    )
+                    associated_element=associated_element,
-                self.cards.append(card)
+                    hebrew_letter_path=hebrew_letter_path,
-                card_number += 1
+                )
+
+            self.cards.append(card)
+            card_number += 1
+
+        return card_number
 
     
     def shuffle(self) -> None:

src/tarot/ui.py

@@ -0,0 +1,872 @@
+"""
+User interface components for displaying Tarot cards.
+
+This module provides a Tkinter-based image displayer for Tarot cards,
+supporting multiple decks and automatic image resolution.
+"""
+
+import os
+import tkinter as tk
+from tkinter import ttk
+from pathlib import Path
+from typing import List, Optional
+
+try:
+    from PIL import Image, ImageTk
+    HAS_PILLOW = True
+except ImportError:
+    HAS_PILLOW = False
+
+from tarot.deck import Card
+from tarot.card.image_loader import ImageDeckLoader
+
+
+class CardDisplay:
+    """
+    Displays Tarot cards using Tkinter and Pillow.
+    """
+    
+    def __init__(self, deck_name: str = "default"):
+        """
+        Initialize the displayer with a specific deck.
+        
+        Args:
+            deck_name: Name of the deck folder in src/tarot/deck/
+        """
+        self.deck_name = deck_name
+        self.deck_path = self._resolve_deck_path(deck_name)
+        self.loader: Optional[ImageDeckLoader] = None
+        
+        if self.deck_path.exists() and self.deck_path.is_dir():
+            try:
+                self.loader = ImageDeckLoader(str(self.deck_path))
+            except Exception as e:
+                print(f"Warning: Failed to initialize deck loader for '{deck_name}': {e}")
+        else:
+            print(f"Warning: Deck folder not found: {self.deck_path}")
+
+    def _resolve_deck_path(self, deck_name: str) -> Path:
+        """Resolve the path to the deck folder."""
+        # src/tarot/ui.py -> src/tarot -> src/tarot/deck
+        current_dir = Path(__file__).parent
+        return current_dir / "deck" / deck_name
+
+    def show_cards(self, cards: List[Card], title: str = "Tarot Spread"):
+        """
+        Display the given cards in a window using SpreadDisplay.
+        
+        Args:
+            cards: List of Card objects to display.
+            title: Window title.
+        """
+        if not HAS_PILLOW:
+            print("Error: Pillow library is not installed. Cannot display images.")
+            print("Please install it with: pip install Pillow")
+            return
+
+        # Import spread classes here to avoid circular imports if any
+        from tarot.card.spread import SpreadPosition, DrawnCard, SpreadReading
+        
+        # Create a dummy spread class since Spread requires a valid name
+        class SimpleSpread:
+            def __init__(self, name, description):
+                self.name = name
+                self.description = description
+                self.positions = []
+
+        # Create positions and drawn cards
+        drawn_cards = []
+        positions = []
+        
+        for i, card in enumerate(cards, 1):
+            # Create a generic position
+            pos = SpreadPosition(
+                number=i,
+                name=f"Card {i}",
+                meaning="Display Card"
+            )
+            positions.append(pos)
+            
+            # Create drawn card
+            drawn = DrawnCard(
+                position=pos,
+                card=card,
+                is_reversed=False
+            )
+            drawn_cards.append(drawn)
+            
+        # Create a synthetic spread
+        spread = SimpleSpread("Card List", title)
+        spread.positions = positions
+        
+        # Create reading
+        reading = SpreadReading(spread, drawn_cards) # type: ignore
+        
+        # Use SpreadDisplay
+        display = SpreadDisplay(reading, self.deck_name)
+        display.root.title(f"{title} - {self.deck_name}")
+        display.run()
+
+
+
+
+class CubeDisplay:
+    """
+    Displays the Cube of Space with navigation.
+    """
+    
+    NAVIGATION = {
+        "North": {"Right": "East", "Left": "West", "Up": "Above", "Down": "Below"},
+        "South": {"Right": "West", "Left": "East", "Up": "Above", "Down": "Below"},
+        "East": {"Right": "South", "Left": "North", "Up": "Above", "Down": "Below"},
+        "West": {"Right": "North", "Left": "South", "Up": "Above", "Down": "Below"},
+        "Above": {"Right": "East", "Left": "West", "Up": "South", "Down": "North"},
+        "Below": {"Right": "East", "Left": "West", "Up": "North", "Down": "South"},
+    }
+
+    def __init__(self, cube, deck_name: str = "default"):
+        self.cube = cube
+        self.deck_name = deck_name
+        self.current_wall_name = "North"
+        self.card_display = CardDisplay(deck_name)
+        self.root = None
+        self.content_frame = None
+        self.zoom_level = 1.0
+
+    def show(self):
+        """Open the Cube display window."""
+        if not HAS_PILLOW:
+            print("Error: Pillow library is not installed. Cannot display images.")
+            return
+
+        self.root = tk.Tk()
+        self.root.title("Cube of Space")
+        
+        # Bind arrow keys for navigation
+        self.root.bind("<Up>", lambda e: self._navigate("Up"))
+        self.root.bind("<Down>", lambda e: self._navigate("Down"))
+        self.root.bind("<Left>", lambda e: self._navigate("Left"))
+        self.root.bind("<Right>", lambda e: self._navigate("Right"))
+        
+        # Bind zoom keys (+ and -)
+        self.root.bind("<plus>", lambda e: self._zoom(1.1))
+        self.root.bind("<equal>", lambda e: self._zoom(1.1))  # Often same key as plus
+        self.root.bind("<minus>", lambda e: self._zoom(0.9))
+        self.root.bind("<underscore>", lambda e: self._zoom(0.9)) # Shift+minus
+        self.root.bind("<KP_Add>", lambda e: self._zoom(1.1)) # Numpad +
+        self.root.bind("<KP_Subtract>", lambda e: self._zoom(0.9)) # Numpad -
+        
+        # Bind WASD for panning
+        self.root.bind("w", lambda e: self._pan_key("up"))
+        self.root.bind("a", lambda e: self._pan_key("left"))
+        self.root.bind("s", lambda e: self._pan_key("down"))
+        self.root.bind("d", lambda e: self._pan_key("right"))
+        self.root.bind("W", lambda e: self._pan_key("up"))
+        self.root.bind("A", lambda e: self._pan_key("left"))
+        self.root.bind("S", lambda e: self._pan_key("down"))
+        self.root.bind("D", lambda e: self._pan_key("right"))
+        
+        # Main container (fills window)
+        self.main_frame = ttk.Frame(self.root)
+        self.main_frame.pack(fill=tk.BOTH, expand=True)
+
+        # Canvas for panning/zooming
+        self.canvas = tk.Canvas(self.main_frame, bg="#f0f0f0")
+        self.canvas.pack(fill=tk.BOTH, expand=True)
+        
+        # Panning bindings
+        self.canvas.bind("<ButtonPress-1>", self._start_pan)
+        self.canvas.bind("<B1-Motion>", self._pan)
+
+        # Content Frame (inside canvas)
+        self.content_frame = ttk.Frame(self.canvas)
+        self.canvas_window = self.canvas.create_window((0, 0), window=self.content_frame, anchor="center")
+        
+        # Overlay Controls
+        # Navigation Frame (Bottom Center)
+        nav_frame = ttk.Frame(self.main_frame, relief="solid", borderwidth=1)
+        nav_frame.place(relx=0.5, rely=0.95, anchor="s")
+        
+        # Zoom Frame (Top Right)
+        zoom_frame = ttk.Frame(self.main_frame, relief="solid", borderwidth=1)
+        zoom_frame.place(relx=0.95, rely=0.05, anchor="ne")
+        
+        # Populate Zoom Frame
+        ttk.Label(zoom_frame, text="Zoom:").pack(side=tk.LEFT, padx=5)
+        ttk.Button(zoom_frame, text="+", width=3, command=lambda: self._zoom(1.22)).pack(side=tk.LEFT)
+        ttk.Button(zoom_frame, text="-", width=3, command=lambda: self._zoom(0.82)).pack(side=tk.LEFT)
+        
+        # Populate Navigation Frame
+        dir_frame = ttk.Frame(nav_frame)
+        dir_frame.pack(side=tk.TOP, padx=5, pady=5)
+        
+        ttk.Button(dir_frame, text="Up", command=lambda: self._navigate("Up")).pack(side=tk.TOP)
+        
+        mid_nav = ttk.Frame(dir_frame)
+        mid_nav.pack(side=tk.TOP)
+        ttk.Button(mid_nav, text="Left", command=lambda: self._navigate("Left")).pack(side=tk.LEFT, padx=5)
+        ttk.Button(mid_nav, text="Right", command=lambda: self._navigate("Right")).pack(side=tk.LEFT, padx=5)
+        
+        ttk.Button(dir_frame, text="Down", command=lambda: self._navigate("Down")).pack(side=tk.TOP)
+        
+        # Initial render
+        self._update_display()
+        
+        # Center window
+        self.root.update_idletasks()
+        width = 800
+        height = 900
+        screen_width = self.root.winfo_screenwidth()
+        screen_height = self.root.winfo_screenheight()
+        x = (screen_width // 2) - (width // 2)
+        y = (screen_height // 2) - (height // 2)
+        self.root.geometry(f'{width}x{height}+{x}+{y}')
+        
+        # Ensure window has focus for keyboard events
+        self.root.focus_force()
+        
+        self.root.mainloop()
+
+    def _start_pan(self, event):
+        """Start panning operation."""
+        self.canvas.scan_mark(event.x_root, event.y_root)
+
+    def _pan(self, event):
+        """Pan the canvas."""
+        self.canvas.scan_dragto(event.x_root, event.y_root, gain=1)
+
+    def _pan_key(self, direction):
+        """Pan the canvas using keys."""
+        if direction == 'up':
+            self.canvas.yview_scroll(-1, "units")
+        elif direction == 'down':
+            self.canvas.yview_scroll(1, "units")
+        elif direction == 'left':
+            self.canvas.xview_scroll(-1, "units")
+        elif direction == 'right':
+            self.canvas.xview_scroll(1, "units")
+
+    def _zoom(self, factor):
+        """Adjust zoom level and redraw, keeping the view centered."""
+        # 1. Capture current state
+        canvas_width = self.canvas.winfo_width()
+        canvas_height = self.canvas.winfo_height()
+        
+        # Center of viewport in canvas coordinates
+        cx = self.canvas.canvasx(canvas_width / 2)
+        cy = self.canvas.canvasy(canvas_height / 2)
+        
+        # Content position
+        bbox = self.canvas.bbox("all")
+        if not bbox:
+            # Should not happen if initialized
+            self.zoom_level *= factor
+            self.zoom_level = max(0.1, min(self.zoom_level, 50.0))
+            self._update_display()
+            return
+
+        content_left = bbox[0]
+        content_top = bbox[1]
+        
+        # Point relative to content
+        rel_x = cx - content_left
+        rel_y = cy - content_top
+        
+        # 2. Update zoom level
+        old_zoom = self.zoom_level
+        self.zoom_level *= factor
+        # Clamp zoom level
+        self.zoom_level = max(0.1, min(self.zoom_level, 50.0))
+        
+        # Calculate effective factor in case of clamping
+        effective_factor = self.zoom_level / old_zoom if old_zoom > 0 else factor
+        
+        # 3. Update display
+        self._update_display()
+        
+        # 4. Restore position
+        # New content position
+        new_bbox = self.canvas.bbox("all")
+        if not new_bbox:
+            return
+            
+        new_content_left = new_bbox[0]
+        new_content_top = new_bbox[1]
+        scroll_width = new_bbox[2] - new_bbox[0]
+        scroll_height = new_bbox[3] - new_bbox[1]
+        
+        # Target point in new content
+        new_rel_x = rel_x * effective_factor
+        new_rel_y = rel_y * effective_factor
+        
+        # Target canvas coordinate for center
+        target_cx = new_content_left + new_rel_x
+        target_cy = new_content_top + new_rel_y
+        
+        # We want target_cx to be at screen center (canvas_width/2)
+        # So left of view should be:
+        view_left = target_cx - (canvas_width / 2)
+        view_top = target_cy - (canvas_height / 2)
+        
+        # Apply scroll
+        if scroll_width > canvas_width:
+            frac_x = (view_left - new_bbox[0]) / scroll_width
+            self.canvas.xview_moveto(frac_x)
+            
+        if scroll_height > canvas_height:
+            frac_y = (view_top - new_bbox[1]) / scroll_height
+            self.canvas.yview_moveto(frac_y)
+
+    def _navigate(self, direction: str):
+        """Navigate to the next wall based on direction."""
+        next_wall = self.NAVIGATION.get(self.current_wall_name, {}).get(direction)
+        if next_wall:
+            self.current_wall_name = next_wall
+            self._update_display()
+
+    def _update_display(self):
+        """Render the current wall."""
+        if self.content_frame is None:
+            return
+
+        # Clear content frame
+        for widget in self.content_frame.winfo_children():
+            widget.destroy()
+            
+        # Title
+        ttk.Label(self.content_frame, text=f"Wall: {self.current_wall_name}", 
+                 font=("Helvetica", 16, "bold")).pack(pady=(0, 20))
+        
+        # Grid for directions
+        grid_frame = ttk.Frame(self.content_frame)
+        grid_frame.pack()
+        
+        wall = self.cube.wall(self.current_wall_name)
+        
+        # Map directions to grid positions (row, col)
+        # 3x3 Grid
+        layout = {
+            "North": (0, 1),
+            "West": (1, 0),
+            "Center": (1, 1),
+            "East": (1, 2),
+            "South": (2, 1)
+        }
+        
+        # Calculate sizes based on zoom
+        cell_width = int(200 * self.zoom_level)
+        cell_height = int(250 * self.zoom_level)
+        img_height = int(200 * self.zoom_level)
+        
+        # Keep images alive
+        self.root.images = []
+        
+        for dir_name, (row, col) in layout.items():
+            direction = wall.direction(dir_name)
+            
+            cell_frame = ttk.Frame(grid_frame, borderwidth=1, relief="solid", width=cell_width, height=cell_height)
+            cell_frame.grid(row=row, column=col, padx=5, pady=5)
+            cell_frame.grid_propagate(False)
+            
+            if direction:
+                card = self._find_card_for_direction(direction)
+                
+                if card:
+                    # Try to load image
+                    img_path = None
+                    if self.card_display.loader:
+                        img_path = self.card_display.loader.get_image_path(card)
+                    if not img_path and card.image_path:
+                        img_path = card.image_path
+                        
+                    if img_path and os.path.exists(img_path):
+                        try:
+                            pil_img = Image.open(img_path)
+                            # Resize for grid
+                            base_height = img_height
+                            h_percent = (base_height / float(pil_img.size[1]))
+                            w_size = int((float(pil_img.size[0]) * float(h_percent)))
+                            pil_img = pil_img.resize((w_size, base_height), Image.Resampling.LANCZOS)
+                            
+                            tk_img = ImageTk.PhotoImage(pil_img)
+                            self.root.images.append(tk_img)
+                            
+                            lbl = tk.Label(cell_frame, image=tk_img, bg="black")
+                            lbl.place(relx=0.5, rely=0.5, anchor="center")
+                        except Exception:
+                            self._render_text_fallback(cell_frame, direction, card.name)
+                    else:
+                        self._render_text_fallback(cell_frame, direction, card.name)
+                else:
+                    self._render_text_fallback(cell_frame, direction)
+            else:
+                ttk.Label(cell_frame, text="Empty").place(relx=0.5, rely=0.5, anchor="center")
+        
+        # Update canvas scrollregion
+        self.content_frame.update_idletasks()
+        self.canvas.config(scrollregion=self.canvas.bbox("all"))
+        
+        # Center content initially if it fits
+        canvas_width = self.canvas.winfo_width()
+        canvas_height = self.canvas.winfo_height()
+        content_width = self.content_frame.winfo_reqwidth()
+        content_height = self.content_frame.winfo_reqheight()
+        
+        if canvas_width > content_width and canvas_height > content_height:
+             self.canvas.coords(self.canvas_window, canvas_width/2, canvas_height/2)
+        else:
+             # Reset to top-left or center of scroll region
+             self.canvas.coords(self.canvas_window, content_width/2, content_height/2)
+        
+        # Bind panning events to all content widgets
+        self._bind_recursive(self.content_frame)
+
+    def _bind_recursive(self, widget):
+        """Recursively bind panning events to widget and its children."""
+        self._bind_pan_events(widget)
+        for child in widget.winfo_children():
+            self._bind_recursive(child)
+
+    def _bind_pan_events(self, widget):
+        """Bind panning events to a widget."""
+        widget.bind("<ButtonPress-1>", self._start_pan)
+        widget.bind("<B1-Motion>", self._pan)
+
+    def _render_text_fallback(self, parent, direction, card_name=None):
+        text = f"{direction.name}\n{direction.letter}"
+        if card_name:
+            text += f"\n({card_name})"
+        ttk.Label(parent, text=text, justify="center").place(relx=0.5, rely=0.5, anchor="center")
+
+    def _find_card_for_direction(self, direction) -> Optional[Card]:
+        """Find the Tarot card associated with a wall direction."""
+        from tarot.tarot_api import Tarot
+        
+        letter_name = direction.letter
+        if not letter_name:
+            return None
+            
+        # Find path with this letter
+        paths = Tarot.tree.path()
+        target_path = None
+        for p in paths.values():
+            if p.hebrew_letter.lower() == letter_name.lower():
+                target_path = p
+                break
+        
+        if target_path and target_path.tarot_trump:
+            # Find card by name (fuzzy match)
+            trump_name = target_path.tarot_trump.lower()
+            
+            for card in Tarot.deck.card.filter():
+                c_name = card.name.lower()
+                # Check if card name is contained in trump name (e.g. "fool" in "0 - the fool")
+                # Or if trump name is contained in card name
+                if c_name in trump_name or trump_name in c_name:
+                    return card
+                    
+        return None
+
+
+def display_cards(cards: List[Card], deck_name: str = "default"):
+    """
+    Convenience function to display cards.
+    
+    Args:
+        cards: List of Card objects to display
+        deck_name: Name of the deck to use (folder name in src/tarot/deck/)
+    """
+    display = CardDisplay(deck_name)
+    display.show_cards(cards)
+
+
+def display_cube(cube=None, deck_name: str = "default"):
+    """
+    Display the Cube of Space with interactive navigation.
+    
+    Args:
+        cube: Cube object (optional, defaults to Tarot.cube)
+        deck_name: Name of the deck to use
+    """
+    if cube is None:
+        from tarot.tarot_api import Tarot
+        cube = Tarot.cube
+        
+    display = CubeDisplay(cube, deck_name)
+    display.show()
+
+
+class SpreadDisplay:
+    """
+    Displays a Tarot spread visually using Tkinter and Pillow.
+    """
+    
+    # Layout definitions: {spread_name: {position_number: {'pos': (x, y), 'rotate': degrees}}}
+    # Coordinates are relative grid units (approx card width/height)
+    # Using 1.02 spacing for tight layout
+    LAYOUTS = {
+        'Celtic Cross': {
+            1: {'pos': (0, 0)},
+            2: {'pos': (0, 0), 'rotate': 90, 'z': 10}, # Top layer
+            3: {'pos': (0, -1.02)},
+            4: {'pos': (0, 1.02)},
+            5: {'pos': (-1.02, 0)},
+            6: {'pos': (1.02, 0)},
+            7: {'pos': (2.1, 1.53)},   # 1.5 * 1.02
+            8: {'pos': (2.1, 0.51)},   # 0.5 * 1.02
+            9: {'pos': (2.1, -0.51)},
+            10: {'pos': (2.1, -1.53)}
+        },
+        '3-Card Spread': {
+            1: {'pos': (-1.02, 0)},
+            2: {'pos': (0, 0)},
+            3: {'pos': (1.02, 0)}
+        },
+        'Golden Dawn 3-Card': {
+            1: {'pos': (0, -1.02)},
+            2: {'pos': (-1.02, 0.8)},
+            3: {'pos': (1.02, 0.8)}
+        },
+        'Horseshoe': {
+            1: {'pos': (-3.06, 1.02)},
+            2: {'pos': (-2.04, 0)},
+            3: {'pos': (-1.02, -0.51)},
+            4: {'pos': (0, -1.02)},
+            5: {'pos': (1.02, -0.51)},
+            6: {'pos': (2.04, 0)},
+            7: {'pos': (3.06, 1.02)}
+        },
+        'Pentagram': {
+            1: {'pos': (0, -1.5)},      # Spirit (Top)
+            2: {'pos': (1.5, -0.4)},    # Fire (Right Top)
+            3: {'pos': (1.0, 1.5)},     # Water (Right Bottom)
+            4: {'pos': (-1.0, 1.5)},    # Air (Left Bottom)
+            5: {'pos': (-1.5, -0.4)}    # Earth (Left Top)
+        },
+        'Relationship': {
+            1: {'pos': (-1.5, 0)},      # You
+            2: {'pos': (1.5, 0)},       # Them
+            3: {'pos': (0, -1.02)},     # Relationship (Center Top)
+            4: {'pos': (0, 0.5)},       # Challenge (Center Bottom)
+            5: {'pos': (0, 2.0)}        # Outcome (Bottom)
+        },
+        'Yes or No': {
+            1: {'pos': (0, 0)}
+        }
+    }
+
+    def __init__(self, reading, deck_name="default"):
+        self.reading = reading
+        self.root = tk.Tk()
+        self.root.title(f"Tarot Spread: {reading.spread.name}")
+        self.root.geometry("1200x900")
+        
+        self.zoom_level = 1.0
+        self.show_text = True
+        self.show_top_card = True
+        self.drag_data = {"x": 0, "y": 0}
+        self._tk_images = [] # Keep references
+        
+        # Setup UI
+        self._setup_ui()
+        
+        # Load images
+        current_dir = Path(__file__).parent
+        deck_path = current_dir / "deck" / deck_name
+        
+        self.image_loader = None
+        if deck_path.exists() and deck_path.is_dir():
+            try:
+                self.image_loader = ImageDeckLoader(str(deck_path))
+            except Exception as e:
+                print(f"Warning: Failed to initialize deck loader: {e}")
+        
+        # Initial draw
+        self._draw_spread()
+        
+        # Center view
+        self._center_view()
+
+    def _setup_ui(self):
+        # Toolbar
+        toolbar = ttk.Frame(self.root)
+        toolbar.pack(side=tk.TOP, fill=tk.X)
+        
+        ttk.Button(toolbar, text="Zoom In (+)", command=lambda: self._zoom(1.2)).pack(side=tk.LEFT, padx=2)
+        ttk.Button(toolbar, text="Zoom Out (-)", command=lambda: self._zoom(0.8)).pack(side=tk.LEFT, padx=2)
+        ttk.Button(toolbar, text="Reset View", command=self._reset_view).pack(side=tk.LEFT, padx=2)
+        ttk.Button(toolbar, text="Toggle Text", command=self._toggle_text).pack(side=tk.LEFT, padx=2)
+        
+        # Only show toggle top card if relevant
+        if self.reading.spread.name == 'Celtic Cross':
+             ttk.Button(toolbar, text="Toggle Cross", command=self._toggle_top_card).pack(side=tk.LEFT, padx=2)
+        
+        # Canvas
+        self.canvas = tk.Canvas(self.root, bg="#2c3e50")
+        self.canvas.pack(fill=tk.BOTH, expand=True)
+        
+        # Bindings
+        self.canvas.bind("<ButtonPress-1>", self._on_drag_start)
+        self.canvas.bind("<B1-Motion>", self._on_drag_motion)
+        self.canvas.bind("<MouseWheel>", self._on_mousewheel)
+        # Linux scroll
+        self.canvas.bind("<Button-4>", lambda e: self._zoom(1.1))
+        self.canvas.bind("<Button-5>", lambda e: self._zoom(0.9))
+
+    def _draw_spread(self):
+        self.canvas.delete("all")
+        self._tk_images.clear()
+        
+        layout = self.LAYOUTS.get(self.reading.spread.name)
+        if not layout:
+            # Fallback to grid if layout not defined
+            self._draw_grid_fallback()
+            return
+
+        # Base dimensions
+        card_width = 100 * self.zoom_level
+        card_height = 150 * self.zoom_level
+        
+        # Spacing units
+        unit_x = card_width
+        unit_y = card_height
+        
+        # Center of virtual space (arbitrary large number to allow scrolling)
+        cx, cy = 2000, 2000
+        
+        min_x, min_y = float('inf'), float('inf')
+        max_x, max_y = float('-inf'), float('-inf')
+        
+        # Sort cards by z-index (default 0)
+        cards_to_draw = []
+        for drawn in self.reading.drawn_cards:
+            pos_data = layout.get(drawn.position.number)
+            if not pos_data:
+                continue
+            
+            z_index = pos_data.get('z', 0)
+            
+            # Skip if top card is hidden
+            if z_index > 0 and not self.show_top_card:
+                continue
+                
+            cards_to_draw.append((drawn, pos_data, z_index))
+            
+        # Sort by z-index ascending
+        cards_to_draw.sort(key=lambda x: x[2])
+        
+        for drawn, pos_data, _ in cards_to_draw:
+            rel_x, rel_y = pos_data['pos']
+            rotation = pos_data.get('rotate', 0)
+            
+            # Calculate position
+            x = cx + (rel_x * unit_x)
+            y = cy + (rel_y * unit_y)
+            
+            # Update bounds
+            # x, y is center
+            half_w = card_width / 2
+            half_h = card_height / 2
+            
+            # If rotated 90 deg, width and height swap for bounding box
+            if abs(rotation % 180) == 90:
+                 half_w, half_h = half_h, half_w
+
+            min_x = min(min_x, x - half_w)
+            max_x = max(max_x, x + half_w)
+            min_y = min(min_y, y - half_h)
+            max_y = max(max_y, y + half_h)
+            
+            # Draw card
+            self._draw_card(drawn, x, y, card_width, card_height, rotation)
+            
+        # Set scroll region
+        padding = 50 * self.zoom_level
+        self.canvas.configure(scrollregion=(min_x - padding, min_y - padding, max_x + padding, max_y + padding))
+
+    def _draw_card(self, drawn, x, y, w, h, layout_rotation):
+        card_name = drawn.card.name
+        
+        # Get image
+        pil_image = None
+        if self.image_loader:
+            img_path = self.image_loader.get_image_path(drawn.card)
+            if img_path and os.path.exists(img_path):
+                try:
+                    pil_image = Image.open(img_path)
+                except Exception as e:
+                    print(f"Error loading image for {card_name}: {e}")
+        
+        if not pil_image:
+            # Draw placeholder
+            self.canvas.create_rectangle(x-w/2, y-h/2, x+w/2, y+h/2, fill="white", outline="black")
+            self.canvas.create_text(x, y, text=card_name, width=w-10)
+        else:
+            # Total rotation
+            rotation = layout_rotation
+            if drawn.is_reversed:
+                rotation += 180
+                
+            # Resize
+            # Note: We resize to w, h BEFORE rotation for consistency with layout
+            pil_image = pil_image.resize((int(w), int(h)), Image.Resampling.LANCZOS)
+            
+            # Rotate
+            if rotation % 360 != 0:
+                pil_image = pil_image.rotate(rotation, expand=True)
+                
+            # Convert to ImageTk
+            tk_image = ImageTk.PhotoImage(pil_image)
+            self._tk_images.append(tk_image)
+            
+            self.canvas.create_image(x, y, image=tk_image)
+        
+        if not self.show_text:
+            return
+
+        # Text Overlay
+        # Calculate visual dimensions
+        is_vertical = (layout_rotation % 180 == 0)
+        vis_w = w if is_vertical else h
+        vis_h = h if is_vertical else w
+        
+        # Font setup
+        font_size = max(8, int(10 * self.zoom_level))
+        
+        # Background rectangle for text (bottom of card)
+        # Height needed: approx 3 lines of text
+        text_h = font_size * 3.5
+        
+        bg_x1 = x - vis_w/2
+        bg_y1 = y + vis_h/2 - text_h
+        bg_x2 = x + vis_w/2
+        bg_y2 = y + vis_h/2
+        
+        # Draw semi-transparent-ish background (stipple works on some platforms, otherwise solid)
+        self.canvas.create_rectangle(
+            bg_x1, bg_y1, bg_x2, bg_y2,
+            fill="#000000", stipple="gray75", outline=""
+        )
+        
+        # Position Name
+        self.canvas.create_text(
+            x, bg_y1 + font_size, 
+            text=f"{drawn.position.number}. {drawn.position.name}", 
+            fill="white", 
+            font=("Arial", font_size, "bold"),
+            width=vis_w - 4,
+            justify="center"
+        )
+        
+        # Meaning (shortened)
+        self.canvas.create_text(
+            x, bg_y1 + font_size * 2.2,
+            text=drawn.position.meaning,
+            fill="#ecf0f1",
+            font=("Arial", int(font_size * 0.8)),
+            width=vis_w - 4,
+            justify="center"
+        )
+
+    def _draw_grid_fallback(self):
+        # Simple grid layout if no specific layout defined
+        cx, cy = 2000, 2000
+        card_width = 100 * self.zoom_level
+        card_height = 150 * self.zoom_level
+        padding = 20 * self.zoom_level
+        
+        min_x, min_y = float('inf'), float('inf')
+        max_x, max_y = float('-inf'), float('-inf')
+        
+        cols = 5
+        for i, drawn in enumerate(self.reading.drawn_cards):
+            row = i // cols
+            col = i % cols
+            
+            x = cx + (col - cols/2) * (card_width + padding)
+            y = cy + (row * 1.5) * (card_height + padding)
+            
+            self._draw_card(drawn, x, y, card_width, card_height, 0)
+            
+            # Update bounds (x,y is center)
+            half_w = card_width / 2
+            half_h = card_height / 2
+            
+            min_x = min(min_x, x - half_w)
+            max_x = max(max_x, x + half_w)
+            min_y = min(min_y, y - half_h)
+            max_y = max(max_y, y + half_h)
+            
+        if min_x == float('inf'): # No cards
+             min_x, min_y, max_x, max_y = cx, cy, cx, cy
+
+        scroll_padding = 50 * self.zoom_level
+        self.canvas.configure(scrollregion=(
+            min_x - scroll_padding, 
+            min_y - scroll_padding, 
+            max_x + scroll_padding, 
+            max_y + scroll_padding
+        ))
+
+    def _zoom(self, factor):
+        self.zoom_level *= factor
+        self.zoom_level = max(0.1, min(self.zoom_level, 5.0))
+        self._draw_spread()
+
+    def _toggle_text(self):
+        self.show_text = not self.show_text
+        self._draw_spread()
+
+    def _toggle_top_card(self):
+        self.show_top_card = not self.show_top_card
+        self._draw_spread()
+
+    def _reset_view(self):
+        self.zoom_level = 1.0
+        self._draw_spread()
+        self._center_view()
+
+    def _center_view(self):
+        # Center the scroll region in the window
+        # This is a bit tricky in Tkinter without knowing window size, 
+        # but we can try to scroll to the center of our virtual space (2000, 2000)
+        # We'll just scroll to the middle of the scrollregion
+        self.root.update_idletasks()
+        region = self.canvas.bbox("all")
+        if region:
+            # Scroll to center of content
+            # This requires math with xview_moveto which takes a fraction
+            # For simplicity, we'll just leave it or try to center roughly
+            pass
+
+    def _on_drag_start(self, event):
+        self.canvas.scan_mark(event.x, event.y)
+
+    def _on_drag_motion(self, event):
+        self.canvas.scan_dragto(event.x, event.y, gain=1)
+
+    def _on_mousewheel(self, event):
+        if event.delta > 0:
+            self._zoom(1.1)
+        else:
+            self._zoom(0.9)
+
+    def run(self):
+        self.root.mainloop()
+
+
+def display_spread(reading, deck_name="default"):
+    """
+    Opens a window displaying the given spread reading.
+    
+    Args:
+        reading: A SpreadReading object returned by Tarot.deck.card.spread()
+        deck_name: Name of the deck to use (default: "default")
+    """
+    if not HAS_PILLOW:
+        print("Pillow library not found. Cannot display graphical spread.")
+        print(reading)
+        return
+        
+    display = SpreadDisplay(reading, deck_name)
+    display.run()

src/utils/object_formatting.py

@@ -30,8 +30,10 @@ def is_nested_object(obj: Any) -> bool:
     """
     Check if object is a nested/complex object (not a scalar type).
     
-    Returns True for dataclasses and objects with __dict__ that aren't scalars.
+    Returns True for dataclasses, dicts, and objects with __dict__ that aren't scalars.
     """
+    if isinstance(obj, dict):
+        return True
     if is_dataclass(obj):
         return True
     return hasattr(obj, '__dict__') and not isinstance(obj, SCALAR_TYPES)
@@ -77,10 +79,13 @@ def get_object_attributes(obj: Any) -> List[Tuple[str, Any]]:
     Extract all public attributes from an object.
     
     Returns list of (name, value) tuples, skipping private attributes (starting with '_').
-    Works with both dataclasses and regular objects with __dict__.
+    Works with dataclasses, dicts, and regular objects with __dict__.
     """
     attributes = []
     
+    if isinstance(obj, dict):
+        return list(obj.items())
+    
     if is_dataclass(obj):
         for field_name in obj.__dataclass_fields__:
             value = getattr(obj, field_name, None)

test_visual_spread_v2.py

@@ -0,0 +1,10 @@
+from tarot import Tarot
+from tarot.ui import display_spread
+
+# Draw a spread
+print("Drawing Celtic Cross spread...")
+reading = Tarot.deck.card.spread("Celtic Cross")
+
+# Display it
+print("Displaying spread...")
+display_spread(reading)

tests/test_card_display.py

@@ -0,0 +1,37 @@
+import pytest
+from tarot.ui import CardDisplay
+from tarot.deck import Card
+from unittest.mock import MagicMock, patch
+
+def test_card_display_delegation():
+    """Test that CardDisplay delegates to SpreadDisplay correctly."""
+    with patch('tarot.ui.SpreadDisplay') as MockSpreadDisplay:
+        # Mock HAS_PILLOW to True to ensure we proceed
+        with patch('tarot.ui.HAS_PILLOW', True):
+            display = CardDisplay()
+            
+            # Create dummy card
+            card = MagicMock(spec=Card)
+            card.name = "The Fool"
+            card.image_path = "fool.jpg"
+            cards = [card]
+            
+            display.show_cards(cards, title="Test Spread")
+            
+            # Verify SpreadDisplay was instantiated
+            assert MockSpreadDisplay.call_count == 1
+            
+            # Verify run was called
+            MockSpreadDisplay.return_value.run.assert_called_once()
+            
+            # Verify arguments passed to SpreadDisplay
+            args, _ = MockSpreadDisplay.call_args
+            reading = args[0]
+            deck_name = args[1]
+            
+            assert deck_name == "default"
+            assert reading.spread.name == "Card List"
+            assert reading.spread.description == "Test Spread"
+            assert len(reading.drawn_cards) == 1
+            assert reading.drawn_cards[0].card == card
+            assert reading.drawn_cards[0].position.number == 1

tests/test_cube_ui.py

@@ -0,0 +1,47 @@
+import pytest
+from tarot.ui import CubeDisplay
+from tarot.tarot_api import Tarot
+
+def test_cube_display_init():
+    cube = Tarot.cube
+    display = CubeDisplay(cube, "default")
+    assert display.current_wall_name == "North"
+    assert display.deck_name == "default"
+
+def test_cube_navigation():
+    cube = Tarot.cube
+    display = CubeDisplay(cube)
+    
+    # North -> Right -> East
+    display._navigate("Right")
+    assert display.current_wall_name == "East"
+    
+    # East -> Up -> Above
+    display._navigate("Up")
+    assert display.current_wall_name == "Above"
+    
+    # Above -> Down -> North
+    display._navigate("Down")
+    assert display.current_wall_name == "North"
+    
+    # North -> Left -> West
+    display._navigate("Left")
+    assert display.current_wall_name == "West"
+
+def test_find_card_for_direction():
+    cube = Tarot.cube
+    display = CubeDisplay(cube)
+    
+    # North Wall, Center Direction -> Aleph -> The Fool
+    wall = cube.wall("North")
+    direction = wall.direction("Center") # Should be Aleph?
+    # Wait, let's check what Center of North is.
+    # Actually, let's just mock a direction
+    
+    from kaballah.cube.attributes import WallDirection
+    
+    # Aleph -> The Fool
+    d = WallDirection("Center", "Aleph")
+    card = display._find_card_for_direction(d)
+    assert card is not None
+    assert "Fool" in card.name

tests/test_cube_zoom.py

@@ -0,0 +1,28 @@
+import pytest
+from tarot.ui import CubeDisplay
+from tarot.tarot_api import Tarot
+
+def test_cube_zoom():
+    cube = Tarot.cube
+    display = CubeDisplay(cube)
+    assert display.zoom_level == 1.0
+    
+    display._zoom(1.1)
+    assert display.zoom_level > 1.0
+    
+    display._zoom(0.5)
+    assert display.zoom_level < 1.0
+
+def test_cube_zoom_limits():
+    cube = Tarot.cube
+    display = CubeDisplay(cube)
+    
+    # Test upper limit
+    for _ in range(20):
+        display._zoom(1.5)
+    assert display.zoom_level <= 3.0
+    
+    # Test lower limit
+    for _ in range(20):
+        display._zoom(0.5)
+    assert display.zoom_level >= 0.5

tests/test_cube_zoom_limits.py

@@ -0,0 +1,124 @@
+import pytest
+from tarot.ui import CubeDisplay
+from tarot.tarot_api import Tarot
+import tkinter as tk
+from unittest.mock import MagicMock, patch
+
+def test_zoom_limits():
+    # Mock Tk root
+    class MockRoot:
+        def __init__(self):
+            self.bindings = {}
+            self.images = []
+        def bind(self, key, callback): pass
+        def title(self, _): pass
+        def update_idletasks(self): pass
+        def winfo_reqwidth(self): return 800
+        def winfo_reqheight(self): return 600
+        def winfo_screenwidth(self): return 1920
+        def winfo_screenheight(self): return 1080
+        def geometry(self, _): pass
+        def mainloop(self): pass
+        def focus_force(self): pass
+        
+    # Mock Frame
+    class MockFrame:
+        def __init__(self, master=None, **kwargs):
+            self.children = []
+            self.master = master
+        def pack(self, **kwargs): pass
+        def place(self, **kwargs): pass
+        def grid(self, **kwargs): pass
+        def grid_propagate(self, flag): pass
+        def winfo_children(self): return self.children
+        def destroy(self): pass
+        def update_idletasks(self): pass
+        def winfo_reqwidth(self): return 100
+        def winfo_reqheight(self): return 100
+        def bind(self, event, callback): pass
+        
+    # Mock Canvas
+    class MockCanvas:
+        def __init__(self, master=None, **kwargs):
+            self.master = master
+        def pack(self, **kwargs): pass
+        def bind(self, event, callback): pass
+        def create_window(self, coords, **kwargs): return 1
+        def config(self, **kwargs): pass
+        def bbox(self, tag): return (0,0,100,100)
+        def winfo_width(self): return 800
+        def winfo_height(self): return 600
+        def coords(self, item, x, y): pass
+        def scan_mark(self, x, y): pass
+        def scan_dragto(self, x, y, gain=1): pass
+        def canvasx(self, x): return x
+        def canvasy(self, y): return y
+        def xview_moveto(self, fraction): pass
+        def yview_moveto(self, fraction): pass
+
+    # Monkey patch tk
+    original_tk = tk.Tk
+    original_frame = tk.ttk.Frame
+    original_canvas = tk.Canvas
+    original_label = tk.ttk.Label
+    original_button = tk.ttk.Button
+    
+    # Mock Label and Button
+    class MockWidget:
+        def __init__(self, master=None, **kwargs):
+            self.master = master
+        def pack(self, **kwargs): pass
+        def place(self, **kwargs): pass
+        def grid(self, **kwargs): pass
+        def grid_propagate(self, flag): pass
+        
+    try:
+        tk.Tk = MockRoot
+        tk.ttk.Frame = MockFrame
+        tk.Canvas = MockCanvas
+        tk.ttk.Label = MockWidget
+        tk.ttk.Button = MockWidget
+        
+        # Mock Image to avoid memory issues
+        with patch('PIL.Image.open') as mock_open:
+            mock_img = MagicMock()
+            mock_img.size = (100, 100)
+            mock_img.resize.return_value = mock_img
+            mock_open.return_value = mock_img
+            
+            with patch('PIL.ImageTk.PhotoImage') as mock_photo:
+                
+                cube = Tarot.cube
+                display = CubeDisplay(cube)
+                display.root = MockRoot()
+                display.canvas = MockCanvas()
+                display.content_frame = MockFrame()
+                display.canvas_window = 1 # Mock window ID
+                
+                # Test initial zoom
+                assert display.zoom_level == 1.0
+                
+                # Test zoom in
+                display._zoom(1.22)
+                assert display.zoom_level == 1.22
+                
+                # Test max limit (should be 50.0)
+                # Zoom way in
+                for _ in range(100):
+                    display._zoom(1.22)
+                    
+                assert display.zoom_level == 50.0
+                
+                # Test min limit (should be 0.1)
+                # Zoom way out
+                for _ in range(200):
+                    display._zoom(0.5)
+                    
+                assert display.zoom_level == 0.1
+        
+    finally:
+        tk.Tk = original_tk
+        tk.ttk.Frame = original_frame
+        tk.Canvas = original_canvas
+        tk.ttk.Label = original_label
+        tk.ttk.Button = original_button

tests/test_ui.py

@@ -0,0 +1,18 @@
+import pytest
+from pathlib import Path
+from tarot.ui import CardDisplay
+
+def test_card_display_init():
+    display = CardDisplay("default")
+    assert display.deck_name == "default"
+    # Check if path resolves correctly relative to src/tarot/ui.py
+    # src/tarot/ui.py -> src/tarot -> src/tarot/deck/default
+    expected_suffix = os.path.join("src", "tarot", "deck", "default")
+    assert str(display.deck_path).endswith(expected_suffix) or str(display.deck_path).endswith("default")
+
+def test_card_display_resolve_path():
+    display = CardDisplay("thoth")
+    assert display.deck_name == "thoth"
+    assert str(display.deck_path).endswith("thoth")
+
+import os

tests/test_ui_binding_recursive.py

@@ -0,0 +1,60 @@
+import pytest
+from tarot.ui import CubeDisplay
+from tarot.tarot_api import Tarot
+import tkinter as tk
+
+def test_recursive_binding():
+    # Mock Tk root and widgets
+    class MockWidget:
+        def __init__(self):
+            self.children = []
+            self.bindings = {}
+        
+        def bind(self, key, callback):
+            self.bindings[key] = callback
+            
+        def winfo_children(self):
+            return self.children
+            
+        def add_child(self, child):
+            self.children.append(child)
+
+    # Monkey patch tk
+    original_tk = tk.Tk
+    original_frame = tk.ttk.Frame
+    
+    try:
+        # We don't need to mock everything, just enough to test _bind_recursive
+        
+        cube = Tarot.cube
+        # We can instantiate CubeDisplay without showing it
+        display = CubeDisplay(cube)
+        
+        # Create a mock widget tree
+        parent = MockWidget()
+        child1 = MockWidget()
+        child2 = MockWidget()
+        grandchild = MockWidget()
+        
+        parent.add_child(child1)
+        parent.add_child(child2)
+        child1.add_child(grandchild)
+        
+        # Run recursive binding
+        display._bind_recursive(parent)
+        
+        # Verify bindings
+        assert "<ButtonPress-1>" in parent.bindings
+        assert "<B1-Motion>" in parent.bindings
+        
+        assert "<ButtonPress-1>" in child1.bindings
+        assert "<B1-Motion>" in child1.bindings
+        
+        assert "<ButtonPress-1>" in child2.bindings
+        assert "<B1-Motion>" in child2.bindings
+        
+        assert "<ButtonPress-1>" in grandchild.bindings
+        assert "<B1-Motion>" in grandchild.bindings
+        
+    finally:
+        pass

tests/test_ui_bindings.py

@@ -0,0 +1,72 @@
+import pytest
+from tarot.ui import CubeDisplay
+from tarot.tarot_api import Tarot
+import tkinter as tk
+
+def test_zoom_key_bindings():
+    # This test verifies that the bindings are set up, 
+    # but cannot easily simulate key presses in headless environment.
+    # We check if the bind method was called with correct keys.
+    
+    # Mock Tk root
+    class MockRoot:
+        def __init__(self):
+            self.bindings = {}
+        
+        def bind(self, key, callback):
+            self.bindings[key] = callback
+            
+        def title(self, _): pass
+        def update_idletasks(self): pass
+        def winfo_reqwidth(self): return 800
+        def winfo_reqheight(self): return 600
+        def winfo_screenwidth(self): return 1920
+        def winfo_screenheight(self): return 1080
+        def geometry(self, _): pass
+        def mainloop(self): pass
+        def focus_force(self): pass
+        
+    # Mock Frame
+    class MockFrame:
+        def __init__(self, master=None, **kwargs):
+            self.children = []
+        def pack(self, **kwargs): pass
+        def winfo_children(self): return self.children
+        def destroy(self): pass
+    
+    # Monkey patch tk
+    original_tk = tk.Tk
+    original_frame = tk.ttk.Frame
+    
+    try:
+        tk.Tk = MockRoot
+        tk.ttk.Frame = MockFrame
+        
+        cube = Tarot.cube
+        display = CubeDisplay(cube)
+        
+        # We need to call show() to trigger bindings, but avoid mainloop
+        # We can't easily mock show() without refactoring, 
+        # so we'll just inspect the code logic or trust the manual test.
+        # However, we can manually call the binding logic if we extract it.
+        
+        # Since we can't easily mock the entire UI startup in a unit test without
+        # a display, we'll rely on the fact that we added the bindings in the code.
+        pass
+        
+    finally:
+        tk.Tk = original_tk
+        tk.ttk.Frame = original_frame
+
+def test_zoom_logic_direct():
+    cube = Tarot.cube
+    display = CubeDisplay(cube)
+    display.zoom_level = 1.0
+    
+    # Simulate + key press effect
+    display._zoom(1.1)
+    assert display.zoom_level > 1.0
+    
+    # Simulate - key press effect
+    display._zoom(0.9)
+    assert display.zoom_level < 1.1

tests/test_ui_panning.py

@@ -0,0 +1,84 @@
+import pytest
+from tarot.ui import CubeDisplay
+from tarot.tarot_api import Tarot
+import tkinter as tk
+
+def test_canvas_structure():
+    # Mock Tk root
+    class MockRoot:
+        def __init__(self):
+            self.bindings = {}
+        def bind(self, key, callback): pass
+        def title(self, _): pass
+        def update_idletasks(self): pass
+        def winfo_reqwidth(self): return 800
+        def winfo_reqheight(self): return 600
+        def winfo_screenwidth(self): return 1920
+        def winfo_screenheight(self): return 1080
+        def geometry(self, _): pass
+        def mainloop(self): pass
+        def focus_force(self): pass
+        
+    # Mock Frame
+    class MockFrame:
+        def __init__(self, master=None, **kwargs):
+            self.children = []
+            self.master = master
+        def pack(self, **kwargs): pass
+        def place(self, **kwargs): pass
+        def winfo_children(self): return self.children
+        def destroy(self): pass
+        def update_idletasks(self): pass
+        def winfo_reqwidth(self): return 100
+        def winfo_reqheight(self): return 100
+        
+    # Mock Canvas
+    class MockCanvas:
+        def __init__(self, master=None, **kwargs):
+            self.master = master
+        def pack(self, **kwargs): pass
+        def bind(self, event, callback): pass
+        def create_window(self, coords, **kwargs): return 1
+        def config(self, **kwargs): pass
+        def bbox(self, tag): return (0,0,100,100)
+        def winfo_width(self): return 800
+        def winfo_height(self): return 600
+        def coords(self, item, x, y): pass
+        def scan_mark(self, x, y): pass
+        def scan_dragto(self, x, y, gain=1): pass
+
+    # Monkey patch tk
+    original_tk = tk.Tk
+    original_frame = tk.ttk.Frame
+    original_canvas = tk.Canvas
+    
+    try:
+        tk.Tk = MockRoot
+        tk.ttk.Frame = MockFrame
+        tk.Canvas = MockCanvas
+        
+        cube = Tarot.cube
+        display = CubeDisplay(cube)
+        
+        # Trigger show to build UI
+        # We can't fully run show() because of mainloop, but we can instantiate parts
+        # Actually, show() creates the root.
+        # Let's just verify the structure by inspecting the code or trusting the manual test.
+        # But we can test the pan methods directly.
+        
+        display.canvas = MockCanvas()
+        
+        # Test pan methods
+        class MockEvent:
+            x = 10
+            y = 20
+            x_root = 110
+            y_root = 120
+            
+        display._start_pan(MockEvent())
+        display._pan(MockEvent())
+        
+    finally:
+        tk.Tk = original_tk
+        tk.ttk.Frame = original_frame
+        tk.Canvas = original_canvas

tests/test_ui_wasd_panning.py

@@ -0,0 +1,128 @@
+import pytest
+from tarot.ui import CubeDisplay
+from tarot.tarot_api import Tarot
+import tkinter as tk
+from unittest.mock import MagicMock, patch
+
+def test_wasd_panning():
+    # Mock Tk root
+    class MockRoot:
+        def __init__(self):
+            self.bindings = {}
+            self.images = []
+        def bind(self, key, callback): 
+            self.bindings[key] = callback
+        def title(self, _): pass
+        def update_idletasks(self): pass
+        def winfo_reqwidth(self): return 800
+        def winfo_reqheight(self): return 600
+        def winfo_screenwidth(self): return 1920
+        def winfo_screenheight(self): return 1080
+        def geometry(self, _): pass
+        def mainloop(self): pass
+        def focus_force(self): pass
+        
+    # Mock Frame
+    class MockFrame:
+        def __init__(self, master=None, **kwargs):
+            self.children = []
+            self.master = master
+        def pack(self, **kwargs): pass
+        def place(self, **kwargs): pass
+        def grid(self, **kwargs): pass
+        def grid_propagate(self, flag): pass
+        def winfo_children(self): return self.children
+        def destroy(self): pass
+        def update_idletasks(self): pass
+        def winfo_reqwidth(self): return 100
+        def winfo_reqheight(self): return 100
+        def bind(self, event, callback): pass
+        
+    # Mock Canvas
+    class MockCanvas:
+        def __init__(self, master=None, **kwargs):
+            self.master = master
+            self.x_scrolls = []
+            self.y_scrolls = []
+            
+        def pack(self, **kwargs): pass
+        def bind(self, event, callback): pass
+        def create_window(self, coords, **kwargs): return 1
+        def config(self, **kwargs): pass
+        def bbox(self, tag): return (0,0,100,100)
+        def winfo_width(self): return 800
+        def winfo_height(self): return 600
+        def coords(self, item, x, y): pass
+        def scan_mark(self, x, y): pass
+        def scan_dragto(self, x, y, gain=1): pass
+        def canvasx(self, x): return x
+        def canvasy(self, y): return y
+        def xview_moveto(self, fraction): pass
+        def yview_moveto(self, fraction): pass
+        
+        def xview_scroll(self, number, what):
+            self.x_scrolls.append((number, what))
+            
+        def yview_scroll(self, number, what):
+            self.y_scrolls.append((number, what))
+
+    # Monkey patch tk
+    original_tk = tk.Tk
+    original_frame = tk.ttk.Frame
+    original_canvas = tk.Canvas
+    original_label = tk.ttk.Label
+    original_button = tk.ttk.Button
+    
+    # Mock Label and Button
+    class MockWidget:
+        def __init__(self, master=None, **kwargs):
+            self.master = master
+        def pack(self, **kwargs): pass
+        def place(self, **kwargs): pass
+        def grid(self, **kwargs): pass
+        def grid_propagate(self, flag): pass
+        
+    try:
+        tk.Tk = MockRoot
+        tk.ttk.Frame = MockFrame
+        tk.Canvas = MockCanvas
+        tk.ttk.Label = MockWidget
+        tk.ttk.Button = MockWidget
+        
+        # Mock Image to avoid memory issues
+        with patch('PIL.Image.open') as mock_open:
+            mock_img = MagicMock()
+            mock_img.size = (100, 100)
+            mock_img.resize.return_value = mock_img
+            mock_open.return_value = mock_img
+            
+            with patch('PIL.ImageTk.PhotoImage') as mock_photo:
+                
+                cube = Tarot.cube
+                display = CubeDisplay(cube)
+                display.root = MockRoot()
+                display.canvas = MockCanvas()
+                display.content_frame = MockFrame()
+                display.canvas_window = 1 
+                
+                # Manually trigger bindings (since we can't easily simulate key press in mock root without event loop)
+                # But we can call _pan_key directly to test logic
+                
+                display._pan_key("up")
+                assert display.canvas.y_scrolls[-1] == (-1, "units")
+                
+                display._pan_key("down")
+                assert display.canvas.y_scrolls[-1] == (1, "units")
+                
+                display._pan_key("left")
+                assert display.canvas.x_scrolls[-1] == (-1, "units")
+                
+                display._pan_key("right")
+                assert display.canvas.x_scrolls[-1] == (1, "units")
+                
+    finally:
+        tk.Tk = original_tk
+        tk.ttk.Frame = original_frame
+        tk.Canvas = original_canvas
+        tk.ttk.Label = original_label
+        tk.ttk.Button = original_button

typer-test.py

@@ -0,0 +1,908 @@
+"""Typer-based CLI for quick Tarot exploration with completions.
+
+Run `python typer-test.py --help` for commands. Install shell completions with
+`python typer-test.py --install-completion`.
+"""
+
+from __future__ import annotations
+
+import ast
+import inspect
+import shlex
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from letter import letter as letter_ns
+
+try:
+    from prompt_toolkit import PromptSession
+    from prompt_toolkit.completion import Completer, Completion
+except ImportError:  # pragma: no cover - optional at runtime
+    PromptSession = None  # type: ignore
+    Completer = object  # type: ignore
+    Completion = object  # type: ignore
+    WordCompleter = None  # type: ignore
+
+
+# Ensure the src directory is on sys.path when running from repo root
+ROOT = Path(__file__).resolve().parent
+SRC_DIR = ROOT / "src"
+if str(SRC_DIR) not in sys.path:
+    sys.path.insert(0, str(SRC_DIR))
+
+from cli_renderers import Renderer  # noqa: E402
+from tarot import Card, Tarot, Tree, Cube  # noqa: E402
+
+
+app = typer.Typer(add_completion=True, help="CLI playground for the Tarot API.")
+tree_app = typer.Typer(help="Tree of Life commands. Examples: tree sephera 1; tree path 11.")
+cube_app = typer.Typer(help="Cube of Space commands. Examples: cube wall North; cube direction North East.")
+letter_app = typer.Typer(help="Letter/I Ching/Periodic commands. Examples: letter alphabet; letter cipher; letter char Aleph.")
+console = Console()
+renderer = Renderer(console)
+_render_value = renderer.render_value
+_print_kv_table = renderer.print_kv_table
+_print_rows_table = renderer.print_rows_table
+_print_cards_table = renderer.print_cards_table
+EXPR_NO_MATCH = object()
+
+SAFE_ROOTS: Dict[str, Any] = {
+    "tarot": Tarot,
+    "tree": Tree,
+    "cube": Cube,
+    "letter": letter_ns,
+}
+
+_MISSING_DOCS: Set[str] = set()
+
+
+ROOT_COMMANDS = [
+    "tarot",
+    "search",
+    "planet",
+    "hexagram",
+    "tree",
+    "cube",
+    "letter",
+    "help",
+    "quit",
+    "exit",
+]
+
+
+def _base_keywords() -> List[str]:
+    return list(ROOT_COMMANDS)
+
+SUITS = ("Cups", "Pentacles", "Swords", "Wands")
+ARCANA = ("Major", "Minor")
+
+
+def _ensure_deck() -> None:
+    """Make sure the shared deck is initialized before use."""
+
+    Tarot.deck.card._ensure_initialized()  # type: ignore[attr-defined]
+
+
+def _complete_suit(ctx: typer.Context, incomplete: str) -> List[str]:
+    return [s for s in SUITS if s.lower().startswith(incomplete.lower())]
+
+
+def _complete_arcana(ctx: typer.Context, incomplete: str) -> List[str]:
+    return [a for a in ARCANA if a.lower().startswith(incomplete.lower())]
+
+
+def _complete_planet_name(ctx: typer.Context, incomplete: str) -> List[str]:
+    try:
+        planets = Tarot.planet()  # type: ignore[assignment]
+    except Exception:
+        return []
+    names = list(planets.keys()) if isinstance(planets, dict) else []
+    return [n for n in names if n.lower().startswith(incomplete.lower())]
+
+
+def _complete_hexagram(ctx: typer.Context, incomplete: str) -> List[str]:
+    try:
+        hexagrams = Tarot.hexagram()  # type: ignore[assignment]
+    except Exception:
+        return []
+    nums = [str(k) for k in hexagrams.keys()] if isinstance(hexagrams, dict) else []
+    return [n for n in nums if n.startswith(incomplete)]
+
+
+def _planet_names() -> List[str]:
+    try:
+        planets = Tarot.planet()  # type: ignore[assignment]
+    except Exception:
+        return []
+    return list(planets.keys()) if isinstance(planets, dict) else []
+
+
+def _hexagram_numbers() -> List[str]:
+    try:
+        hexagrams = Tarot.hexagram()  # type: ignore[assignment]
+    except Exception:
+        return []
+    return [str(k) for k in hexagrams.keys()] if isinstance(hexagrams, dict) else []
+
+
+def _sephera_numbers() -> List[str]:
+    try:
+        from tarot import Tree
+
+        seph = Tree.sephera()  # type: ignore[assignment]
+    except Exception:
+        return []
+    return [str(k) for k in seph.keys()] if isinstance(seph, dict) else []
+
+
+def _path_numbers() -> List[str]:
+    try:
+        from tarot import Tree
+
+        paths = Tree.path()  # type: ignore[assignment]
+    except Exception:
+        return []
+    return [str(k) for k in paths.keys()] if isinstance(paths, dict) else []
+
+
+def _wall_names() -> List[str]:
+    return ["North", "South", "East", "West", "Above", "Below"]
+
+
+def _alphabet_names() -> List[str]:
+    try:
+        alph = letter_ns.alphabet.all()
+    except Exception:
+        return []
+    return list(alph.keys()) if isinstance(alph, dict) else []
+
+
+def _cipher_names() -> List[str]:
+    try:
+        ciphers = letter_ns.cipher.all()
+    except Exception:
+        return []
+    return list(ciphers.keys()) if isinstance(ciphers, dict) else []
+
+
+def _letter_names() -> List[str]:
+    try:
+        letters = letter_ns.letter.all()
+    except Exception:
+        return []
+    return list(letters.keys()) if isinstance(letters, dict) else []
+
+
+def _periodic_symbols() -> List[str]:
+    try:
+        periodic = letter_ns.periodic.all()
+    except Exception:
+        return []
+    return list(periodic.keys()) if isinstance(periodic, dict) else []
+
+
+def _current_fragment(text: str) -> str:
+    stripped = text.rstrip()
+    if not stripped:
+        return ""
+    last_token = stripped.split()[-1]
+    if "." in last_token:
+        return last_token.rsplit(".", 1)[-1]
+    return last_token
+
+
+def _completion_candidates(text: str) -> List[str]:
+    stripped = text.rstrip()
+    if not stripped:
+        return _base_keywords()
+    try:
+        tokens = shlex.split(stripped)
+    except ValueError:
+        tokens = stripped.split()
+
+    last_token = tokens[-1] if tokens else ""
+
+    # Dotted path completion
+    if "." in last_token:
+        head, partial = last_token.rsplit(".", 1)
+        target = _safe_eval_expr(head)
+        if target is EXPR_NO_MATCH:
+            return []
+        partial_lower = partial.lower()
+        if isinstance(target, dict):
+            return [str(k) for k in target.keys() if str(k).lower().startswith(partial_lower)]
+        return [name for name in dir(target) if not name.startswith("_") and name.lower().startswith(partial_lower)]
+
+    fragment = last_token.lower() if last_token else ""
+
+    # No tokens yet: suggest root commands
+    if len(tokens) == 0:
+        return [kw for kw in _base_keywords() if kw.lower().startswith(fragment)]
+
+    cmd = tokens[0].lower()
+
+    # First token: suggest matching commands
+    if len(tokens) == 1:
+        return [kw for kw in _base_keywords() if kw.lower().startswith(fragment)]
+
+    # Contextual suggestions per command
+    if cmd == "planet":
+        return [p for p in _planet_names() if p.lower().startswith(fragment)]
+
+    if cmd == "hexagram":
+        return [n for n in _hexagram_numbers() if n.startswith(fragment)]
+
+    if cmd == "tree":
+        if len(tokens) == 2:
+            return [sub for sub in ["sephera", "path"] if sub.startswith(fragment)]
+        if len(tokens) == 3 and tokens[1].lower() == "sephera":
+            return [n for n in _sephera_numbers() if n.startswith(fragment)]
+        if len(tokens) == 3 and tokens[1].lower() == "path":
+            return [n for n in _path_numbers() if n.startswith(fragment)]
+
+    if cmd == "cube":
+        if len(tokens) == 2:
+            return [sub for sub in ["wall", "direction"] if sub.startswith(fragment)]
+        if len(tokens) == 3 and tokens[1].lower() == "wall":
+            return [w for w in _wall_names() if w.lower().startswith(fragment)]
+        if len(tokens) >= 3 and tokens[1].lower() == "direction":
+            # suggest wall name at position 3
+            if len(tokens) == 3:
+                return [w for w in _wall_names() if w.lower().startswith(fragment)]
+            # suggest direction names after wall
+            return [d for d in _direction_names_for_wall(tokens[2]) if d.lower().startswith(fragment)]
+
+    if cmd == "letter":
+        if len(tokens) == 2:
+            return [sub for sub in ["alphabet", "cipher", "char", "periodic"] if sub.startswith(fragment)]
+        if len(tokens) == 3 and tokens[1].lower() == "alphabet":
+            return [a for a in _alphabet_names() if a.lower().startswith(fragment)]
+        if len(tokens) == 3 and tokens[1].lower() == "cipher":
+            return [c for c in _cipher_names() if c.lower().startswith(fragment)]
+        if len(tokens) == 3 and tokens[1].lower() in {"char", "letter"}:
+            return [l for l in _letter_names() if l.lower().startswith(fragment)]
+        if len(tokens) == 3 and tokens[1].lower() == "periodic":
+            return [s for s in _periodic_symbols() if s.lower().startswith(fragment)]
+
+    if cmd == "search":
+        # Simple heuristics: suggest option flags or option values based on prior flag
+        if last_token.startswith("-"):
+            return [opt for opt in ["--suit", "--arcana", "--pip", "-s", "-a", "-p"] if opt.startswith(last_token)]
+        if any(tok in {"--suit", "-s"} for tok in tokens[:-1]):
+            return [s for s in SUITS if s.lower().startswith(fragment)]
+        if any(tok in {"--arcana", "-a"} for tok in tokens[:-1]):
+            return [a for a in ARCANA if a.lower().startswith(fragment)]
+        return []
+
+    # Default: no suggestions
+    return []
+
+
+class DotPathCompleter(Completer):
+    def get_completions(self, document, complete_event):  # type: ignore[override]
+        text = document.text_before_cursor
+        fragment = _current_fragment(text)
+        for cand in _completion_candidates(text):
+            yield Completion(cand, start_position=-len(fragment))
+
+
+def _safe_eval_expr(expr: str) -> Any:
+    expr = expr.strip()
+    if not expr:
+        return EXPR_NO_MATCH
+    try:
+        parsed = ast.parse(expr, mode="eval")
+    except SyntaxError:
+        return EXPR_NO_MATCH
+
+    def _eval_node(node: ast.AST) -> Any:
+        if isinstance(node, ast.Expression):
+            return _eval_node(node.body)
+        if isinstance(node, ast.Name):
+            if node.id in SAFE_ROOTS:
+                return SAFE_ROOTS[node.id]
+            raise ValueError("Name not allowed")
+        if isinstance(node, ast.Attribute):
+            value = _eval_node(node.value)
+            return getattr(value, node.attr)
+        if isinstance(node, ast.Call):
+            func = _eval_node(node.func)
+            args = [_eval_node(arg) for arg in node.args]
+            kwargs = {kw.arg: _eval_node(kw.value) for kw in node.keywords if kw.arg is not None}
+            return func(*args, **kwargs)
+        if isinstance(node, ast.Constant):
+            return node.value
+        raise ValueError("Expression not allowed")
+
+    try:
+        return _eval_node(parsed)
+    except Exception:
+        return EXPR_NO_MATCH
+
+
+def _search_cards(suit: Optional[str], arcana: Optional[str], pip: Optional[int]) -> List[Card]:
+    _ensure_deck()
+    deck = Tarot.deck.card._deck  # type: ignore[attr-defined]
+    if deck is None:
+        return []
+
+    cards: List[Card] = deck.cards
+    if suit is not None:
+        cards = [
+            card
+            for card in cards
+            if getattr(getattr(card, "suit", None), "name", "").lower() == suit.lower()
+        ]
+    if arcana is not None:
+        cards = [card for card in cards if getattr(card, "arcana", "").lower() == arcana.lower()]
+    if pip is not None:
+        cards = [card for card in cards if getattr(card, "pip", None) == pip]
+    return cards
+@app.command()
+def search(
+    suit: Optional[str] = typer.Option(
+        None, "--suit", "-s", help="Filter by suit", autocompletion=_complete_suit
+    ),
+    arcana: Optional[str] = typer.Option(
+        None, "--arcana", "-a", help="Filter by arcana", autocompletion=_complete_arcana
+    ),
+    pip: Optional[int] = typer.Option(
+        None, "--pip", "-p", help="Filter by pip (1 for Ace, 2-10 for pips)"
+    ),
+) -> None:
+    """Filter cards with autocompleting suit/arcana options."""
+
+    cards = _search_cards(suit, arcana, pip)
+
+    if not cards:
+        typer.echo("No cards matched that filter.")
+        raise typer.Exit(code=0)
+
+def _doc(obj: Any, fallback: str) -> str:
+    return inspect.getdoc(obj) or fallback
+
+
+def _sync_doc(cmd_fn: Any, source_obj: Any) -> None:
+    if cmd_fn is None or source_obj is None:
+        return
+    doc = _doc(source_obj, cmd_fn.__doc__ or "")
+    if doc:
+        cmd_fn.__doc__ = doc
+    else:
+        _MISSING_DOCS.add(cmd_fn.__name__)
+
+
+def _report_missing_docs() -> None:
+    if not _MISSING_DOCS:
+        return
+    console.print(
+        f"[yellow]Docstring missing for: {', '.join(sorted(_MISSING_DOCS))}."
+        " Update source API docstrings to sync help.[/yellow]"
+    )
+
+
+def _print_structure_table() -> None:
+    rows = [
+        ("tarot.deck.card(n)", "Access cards by deck position", "tarot.deck.card(1)"),
+        (
+            "tarot.deck.card.filter(...)",
+            "Filter cards using attributes",
+            "tarot.deck.card.filter(arcana='Major')",
+        ),
+        (
+            "tarot.deck.card.spread(name)",
+            "Draw a spread with random cards",
+            "tarot.deck.card.spread('Celtic Cross')",
+        ),
+        ("tarot.planet()", "Planet correspondences as dict", "tarot.planet()['Venus']"),
+        ("tarot.hexagram()", "I Ching hexagrams as dict", "tarot.hexagram()[1]"),
+        ("tree.sephera(n)", "Kabbalistic sephiroth", "tree.sephera(1)"),
+        ("tree.path(n)", "Paths on the Tree of Life", "tree.path(11)"),
+        ("cube.wall(name)", "Cube of Space walls", "cube.wall('North')"),
+        ("cube.direction(wall, dir)", "Directions on a wall", "cube.direction('North', 'East')"),
+        ("letter.alphabet.all()", "Alphabet metadata", "letter.alphabet.all()['english']"),
+        ("letter.cipher.all()", "Cipher definitions", "letter.cipher.all()['english_simple']"),
+        ("letter.letter.all()", "Letters and properties", "letter.letter.all()['Aleph']"),
+        ("letter.periodic.all()", "Periodic correspondences", "letter.periodic.all()['H']"),
+        ("letter.iching.all()", "I Ching via letter namespace", "letter.iching.all()[1]"),
+    ]
+
+    table = Table(title="Tarot API Map", show_lines=True)
+    table.add_column("Expression", style="cyan")
+    table.add_column("Description")
+    table.add_column("Example")
+    for expr, desc, example in rows:
+        table.add_row(expr, desc, example)
+    console.print(table)
+    console.print(
+        "REPL: type expressions exactly as above; tab completion works per segment. "
+        "CLI shortcuts that remain: search, planet, hexagram, tree, cube, letter."
+    )
+
+
+def _show_sephera(number: Optional[int]) -> None:
+    getattr(Tree, "_ensure_initialized", lambda: None)()
+    data = Tree.sephera(number)
+    if data is None:
+        typer.echo("Sephera not found.")
+        return
+    if isinstance(data, dict):
+        rows: List[List[Any]] = []
+        for num, obj in sorted(data.items()):
+            rows.append([
+                num,
+                getattr(obj, "name", ""),
+                getattr(obj, "hebrew_name", ""),
+                getattr(obj, "planet", ""),
+                getattr(obj, "element", ""),
+            ])
+        _print_rows_table("Sephiroth", ["#", "Name", "Hebrew", "Planet", "Element"], rows)
+    else:
+        attrs = data.__dict__ if hasattr(data, "__dict__") else {"value": data}
+        _print_kv_table(f"Sephera: {getattr(data, 'name', number)}", attrs)
+
+
+def _show_path(number: Optional[int]) -> None:
+    getattr(Tree, "_ensure_initialized", lambda: None)()
+    data = Tree.path(number)
+    if data is None:
+        typer.echo("Path not found.")
+        return
+    if isinstance(data, dict):
+        rows: List[List[Any]] = []
+        for num, obj in sorted(data.items()):
+            rows.append([
+                num,
+                getattr(obj, "name", ""),
+                getattr(obj, "hebrew_letter", getattr(obj, "hebrew", "")),
+                getattr(obj, "planet", getattr(obj, "element", "")),
+            ])
+        _print_rows_table("Paths", ["#", "Name", "Hebrew", "Assoc"], rows)
+    else:
+        attrs = data.__dict__ if hasattr(data, "__dict__") else {"value": data}
+        _print_kv_table(f"Path: {number}", attrs)
+
+
+def _show_walls(name: Optional[str]) -> None:
+    cube_walls = Cube.wall.all() if Cube.wall else []  # type: ignore[attr-defined]
+    if name is None:
+        rows = []
+        for wall in cube_walls:
+            rows.append([
+                getattr(wall, "name", ""),
+                getattr(wall, "element", ""),
+                getattr(wall, "planet", ""),
+                getattr(wall, "opposite", ""),
+            ])
+        _print_rows_table("Cube Walls", ["Wall", "Element", "Planet", "Opposite"], rows)
+        return
+    wall_obj = None
+    for wall in cube_walls:
+        if getattr(wall, "name", "").lower() == name.lower():
+            wall_obj = wall
+            break
+    if wall_obj is None:
+        typer.echo(f"Wall '{name}' not found.")
+        return
+    attrs = wall_obj.__dict__ if hasattr(wall_obj, "__dict__") else {"value": wall_obj}
+    _print_kv_table(f"Wall: {getattr(wall_obj, 'name', name)}", attrs)
+
+
+def _direction_names_for_wall(wall_name: str) -> List[str]:
+    cube_walls = Cube.wall.all() if Cube.wall else []  # type: ignore[attr-defined]
+    for wall in cube_walls:
+        if getattr(wall, "name", "").lower() == wall_name.lower():
+            return list(getattr(wall, "directions", {}).keys()) if hasattr(wall, "directions") else []
+    return []
+
+
+def _show_direction(wall_name: str, direction: Optional[str]) -> None:
+    cube_walls = Cube.wall.all() if Cube.wall else []  # type: ignore[attr-defined]
+    wall_obj = None
+    for wall in cube_walls:
+        if getattr(wall, "name", "").lower() == wall_name.lower():
+            wall_obj = wall
+            break
+    if wall_obj is None:
+        typer.echo(f"Wall '{wall_name}' not found.")
+        return
+    if direction is None:
+        dirs = getattr(wall_obj, "directions", {}) if hasattr(wall_obj, "directions") else {}
+        rows = []
+        for name, dir_obj in dirs.items():
+            rows.append([
+                name,
+                getattr(dir_obj, "element", ""),
+                getattr(dir_obj, "planet", ""),
+            ])
+        _print_rows_table(
+            f"Directions for {getattr(wall_obj, 'name', wall_name)}",
+            ["Direction", "Element", "Planet"],
+            rows,
+        )
+        return
+    dirs = getattr(wall_obj, "directions", {}) if hasattr(wall_obj, "directions") else {}
+    dir_obj = dirs.get(direction.capitalize()) if isinstance(dirs, dict) else None
+    if dir_obj is None:
+        typer.echo(f"Direction '{direction}' not found in wall '{wall_name}'.")
+        return
+    attrs = dir_obj.__dict__ if hasattr(dir_obj, "__dict__") else {"value": dir_obj}
+    _print_kv_table(f"Direction: {direction} ({wall_name})", attrs)
+
+
+def _show_alphabets(name: Optional[str]) -> None:
+    alph = letter_ns.alphabet.all()
+    if not isinstance(alph, dict):
+        typer.echo("Alphabet data unavailable.")
+        return
+    if name is None:
+        rows = [[k, v.get("name", "") if isinstance(v, dict) else ""] for k, v in alph.items()]
+        _print_rows_table("Alphabets", ["Key", "Name"], rows)
+        return
+    obj = alph.get(name)
+    if obj is None:
+        typer.echo(f"Alphabet '{name}' not found.")
+        return
+    attrs = obj if isinstance(obj, dict) else {"value": obj}
+    _print_kv_table(f"Alphabet: {name}", attrs)
+
+
+def _show_ciphers(name: Optional[str]) -> None:
+    ciphers = letter_ns.cipher.all()
+    if not isinstance(ciphers, dict):
+        typer.echo("Cipher data unavailable.")
+        return
+    if name is None:
+        rows = [[k, ""] for k in ciphers.keys()]
+        _print_rows_table("Ciphers", ["Key", ""], rows)
+        return
+    obj = ciphers.get(name)
+    if obj is None:
+        typer.echo(f"Cipher '{name}' not found.")
+        return
+    attrs = obj if isinstance(obj, dict) else {"value": obj}
+    _print_kv_table(f"Cipher: {name}", attrs)
+
+
+def _show_letter_char(name: Optional[str]) -> None:
+    letters = letter_ns.letter.all()
+    if not isinstance(letters, dict):
+        typer.echo("Letter data unavailable.")
+        return
+    if name is None:
+        rows = [[k, getattr(v, "hebrew_name", getattr(v, "name", ""))] for k, v in letters.items()]
+        _print_rows_table("Letters", ["Key", "Name"], rows)
+        return
+    obj = letters.get(name)
+    if obj is None:
+        typer.echo(f"Letter '{name}' not found.")
+        return
+    attrs = obj.__dict__ if hasattr(obj, "__dict__") else {"value": obj}
+    _print_kv_table(f"Letter: {name}", attrs)
+
+
+def _show_periodic(symbol: Optional[str]) -> None:
+    periodic = letter_ns.periodic.all()
+    if not isinstance(periodic, dict):
+        typer.echo("Periodic table data unavailable.")
+        return
+    if symbol is None:
+        rows = [[k, getattr(v, "name", getattr(v, "element", ""))] for k, v in periodic.items()]
+        _print_rows_table("Periodic Table", ["Symbol", "Name"], rows)
+        return
+    obj = periodic.get(symbol)
+    if obj is None:
+        typer.echo(f"Symbol '{symbol}' not found.")
+        return
+    attrs = obj.__dict__ if hasattr(obj, "__dict__") else {"value": obj}
+    _print_kv_table(f"Element: {symbol}", attrs)
+
+
+@app.command()
+def planet(
+    name: Optional[str] = typer.Argument(
+        None, help="Planet name (omit to list all)", autocompletion=_complete_planet_name
+    )
+) -> None:
+    """Show a planet or list all planet names."""
+
+    Tarot._ensure_initialized()  # type: ignore[attr-defined]
+    planets = Tarot.planet()  # type: ignore[assignment]
+    if not isinstance(planets, dict):
+        typer.echo("Planet data unavailable.")
+        raise typer.Exit(code=1)
+
+    if name is None:
+        table = Table(title="Planets", show_header=True)
+        table.add_column("Name")
+        for planet_name in sorted(planets.keys()):
+            table.add_row(planet_name)
+        console.print(table)
+        return
+
+    planet_obj = planets.get(name)
+    if planet_obj is None:
+        typer.echo(f"Planet '{name}' not found.")
+        raise typer.Exit(code=1)
+
+    _render_value(planet_obj)
+
+
+@app.command()
+def hexagram(
+    number: Optional[int] = typer.Argument(
+        None, help="Hexagram number (1-64). Omit to list all.", autocompletion=_complete_hexagram
+    )
+) -> None:
+    """Show an I Ching hexagram or list all numbers."""
+
+    Tarot._ensure_initialized()  # type: ignore[attr-defined]
+    hexagrams = Tarot.hexagram()  # type: ignore[assignment]
+    if not isinstance(hexagrams, dict):
+        typer.echo("Hexagram data unavailable.")
+        raise typer.Exit(code=1)
+
+    if number is None:
+        table = Table(title="Hexagrams", show_header=True)
+        table.add_column("Number")
+        for num in sorted(hexagrams.keys()):
+            table.add_row(str(num))
+        console.print(table)
+        return
+
+    hex_obj = hexagrams.get(number)
+    if hex_obj is None:
+        typer.echo(f"Hexagram '{number}' not found.")
+        raise typer.Exit(code=1)
+
+    attrs = hex_obj.__dict__ if hasattr(hex_obj, "__dict__") else {"value": hex_obj}
+    _print_kv_table(f"Hexagram: {number}", attrs)
+
+
+# Keep CLI command docs in sync with API docstrings
+_sync_doc(planet, getattr(Tarot, "planet", None))
+_sync_doc(hexagram, getattr(Tarot, "hexagram", None))
+
+
+app.add_typer(tree_app, name="tree")
+app.add_typer(cube_app, name="cube")
+app.add_typer(letter_app, name="letter")
+
+
+@tree_app.command("sephera")
+def tree_sephera(number: Optional[int] = typer.Argument(None, autocompletion=_sephera_numbers)) -> None:
+    """List all sephiroth or show a specific one."""
+
+    _show_sephera(number)
+
+
+@tree_app.command("path")
+def tree_path(number: Optional[int] = typer.Argument(None, autocompletion=_path_numbers)) -> None:
+    """List all paths or show a specific one."""
+
+    _show_path(number)
+
+
+@cube_app.command("wall")
+def cube_wall(name: Optional[str] = typer.Argument(None, autocompletion=_wall_names)) -> None:
+    """List walls or show details for a wall."""
+
+    _show_walls(name)
+
+
+@cube_app.command("direction")
+def cube_direction(
+    wall_name: str = typer.Argument(..., autocompletion=_wall_names),
+    direction: Optional[str] = typer.Argument(None),
+) -> None:
+    """List directions for a wall or show one."""
+
+    _show_direction(wall_name, direction)
+
+
+@letter_app.command("alphabet")
+def letter_alphabet(name: Optional[str] = typer.Argument(None, autocompletion=_alphabet_names)) -> None:
+    """List alphabets or show one."""
+
+    _show_alphabets(name)
+
+
+@letter_app.command("cipher")
+def letter_cipher(name: Optional[str] = typer.Argument(None, autocompletion=_cipher_names)) -> None:
+    """List ciphers or show one."""
+
+    _show_ciphers(name)
+
+
+@letter_app.command("char")
+def letter_char(name: Optional[str] = typer.Argument(None, autocompletion=_letter_names)) -> None:
+    """List letters or show one."""
+
+    _show_letter_char(name)
+
+
+@letter_app.command("periodic")
+def letter_periodic(symbol: Optional[str] = typer.Argument(None, autocompletion=_periodic_symbols)) -> None:
+    """List periodic elements or show one."""
+
+    _show_periodic(symbol)
+
+
+# Sync all command docstrings from source APIs (single source of truth)
+_sync_doc(planet, getattr(Tarot, "planet", None))
+_sync_doc(hexagram, getattr(Tarot, "hexagram", None))
+_sync_doc(tree_sephera, getattr(Tree, "sephera", None))
+_sync_doc(tree_path, getattr(Tree, "path", None))
+_sync_doc(cube_wall, getattr(Cube, "wall", None))
+_sync_doc(cube_direction, getattr(Cube, "direction", None))
+_sync_doc(letter_alphabet, getattr(letter_ns, "alphabet", None))
+_sync_doc(letter_cipher, getattr(letter_ns, "cipher", None))
+_sync_doc(letter_char, getattr(letter_ns, "letter", None))
+_sync_doc(letter_periodic, getattr(letter_ns, "periodic", None))
+_report_missing_docs()
+
+
+def _handle_repl_command(parts: List[str], raw_line: str = "") -> bool:
+    if not parts:
+        return True
+    cmd = parts[0].lower()
+
+    if cmd in {"quit", "exit"}:
+        return False
+    if cmd == "help":
+        _print_structure_table()
+        return True
+    if cmd == "search":
+        suit = None
+        arcana = None
+        pip = None
+        tokens = parts[1:]
+        i = 0
+        while i < len(tokens):
+            if tokens[i] in {"--suit", "-s"} and i + 1 < len(tokens):
+                suit = tokens[i + 1]
+                i += 2
+            elif tokens[i] in {"--arcana", "-a"} and i + 1 < len(tokens):
+                arcana = tokens[i + 1]
+                i += 2
+            elif tokens[i] in {"--pip", "-p"} and i + 1 < len(tokens):
+                try:
+                    pip = int(tokens[i + 1])
+                except ValueError:
+                    console.print("Invalid pip value.")
+                    return True
+                i += 2
+            else:
+                i += 1
+        cards = _search_cards(suit, arcana, pip)
+        if not cards:
+            console.print("No cards matched that filter.")
+        else:
+            _print_cards_table(cards)
+        return True
+    if cmd == "planet":
+        planet_name = parts[1] if len(parts) > 1 else None
+        planets = Tarot.planet()  # type: ignore[assignment]
+        if not isinstance(planets, dict):
+            console.print("Planet data unavailable.")
+            return True
+        if planet_name is None:
+            console.print(", ".join(sorted(planets.keys())))
+            return True
+        planet_obj = planets.get(planet_name)
+        if planet_obj is None:
+            console.print(f"Planet '{planet_name}' not found.")
+            return True
+        _render_value(planet_obj)
+        return True
+    if cmd == "hexagram":
+        hex_num = None
+        if len(parts) > 1 and parts[1].isdigit():
+            hex_num = int(parts[1])
+        hexagrams = Tarot.hexagram()  # type: ignore[assignment]
+        if not isinstance(hexagrams, dict):
+            console.print("Hexagram data unavailable.")
+            return True
+        if hex_num is None:
+            console.print(", ".join(str(n) for n in sorted(hexagrams.keys())))
+            return True
+        hex_obj = hexagrams.get(hex_num)
+        if hex_obj is None:
+            console.print(f"Hexagram '{hex_num}' not found.")
+            return True
+        attrs = hex_obj.__dict__ if hasattr(hex_obj, "__dict__") else {"value": hex_obj}
+        _print_kv_table(f"Hexagram: {hex_num}", attrs)
+        return True
+    if cmd == "tree" and len(parts) > 1:
+        sub = parts[1].lower()
+        arg = parts[2] if len(parts) > 2 else None
+        if sub == "sephera":
+            _show_sephera(int(arg)) if arg and arg.isdigit() else _show_sephera(None)
+            return True
+        if sub == "path":
+            _show_path(int(arg)) if arg and arg.isdigit() else _show_path(None)
+            return True
+    if cmd == "cube" and len(parts) > 1:
+        sub = parts[1].lower()
+        arg = parts[2] if len(parts) > 2 else None
+        if sub == "wall":
+            _show_walls(arg)
+            return True
+        if sub == "direction" and len(parts) >= 3:
+            direction = parts[3] if len(parts) > 3 else None
+            _show_direction(parts[2], direction)
+            return True
+    if cmd == "letter" and len(parts) > 1:
+        sub = parts[1].lower()
+        arg = parts[2] if len(parts) > 2 else None
+        if sub == "alphabet":
+            _show_alphabets(arg)
+            return True
+        if sub == "cipher":
+            _show_ciphers(arg)
+            return True
+        if sub in {"char", "letter"}:
+            _show_letter_char(arg)
+            return True
+        if sub == "periodic":
+            _show_periodic(arg)
+            return True
+
+    expr_result = _safe_eval_expr(raw_line or " ".join(parts))
+    if expr_result is not EXPR_NO_MATCH:
+        _render_value(expr_result)
+        return True
+
+    console.print("Unknown command. Type 'help' for the API map or use Python-style expressions.")
+    return True
+
+
+@app.command()
+def repl() -> None:
+    """Interactive loop for quick Tarot exploration."""
+
+    console.print("Type 'help' for the API map, use Python-style expressions, 'quit' to exit.")
+
+    # Build prompt-toolkit completer if available (supports dotted paths)
+    session = None
+    completer = None
+    if PromptSession:
+        completer = DotPathCompleter()
+        session = PromptSession(completer=completer)
+
+    while True:
+        try:
+            if session:
+                line = session.prompt("tarot> ")
+            else:
+                line = input("tarot> ")
+            line = line.strip()
+        except (EOFError, KeyboardInterrupt):
+            console.print("Bye.")
+            break
+        if not line:
+            continue
+        try:
+            parts = shlex.split(line)
+        except ValueError as exc:
+            console.print(f"Parse error: {exc}")
+            continue
+        if not _handle_repl_command(parts, raw_line=line):
+            break
+
+
+if __name__ == "__main__":
+    if len(sys.argv) == 2 and sys.argv[1] in {"-h", "--help"}:
+        _print_structure_table()
+        sys.exit(0)
+
+    # If invoked without a subcommand, drop into the REPL for convenience.
+    if len(sys.argv) == 1:
+        repl()
+    else:
+        app()