slab-cli 0.20.0__tar.gz → 0.22.0__tar.gz

{slab_cli-0.20.0 → slab_cli-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: slab-cli
-Version: 0.20.0
+Version: 0.22.0
 Summary: CLI for the slab trading-card API — catalog, collect, and track your cards from the terminal.
 Author: dev_jeb
 Requires-Dist: slab-schemas>=0.35.0

{slab_cli-0.20.0 → slab_cli-0.22.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "slab-cli"
-version = "0.20.0"
+version = "0.22.0"
 description = "CLI for the slab trading-card API — catalog, collect, and track your cards from the terminal."
 readme = "README.md"
 authors = [{name = "dev_jeb"}]

{slab_cli-0.20.0 → slab_cli-0.22.0}/src/slab_cli/browse.py

@@ -321,6 +321,7 @@ def browse(
     footer: str | None = None,
     start: int = 0,
     detail: Callable[[Any], "Page | None"] | None = None,
+    receipt: "Page | None" = None,
 ) -> Any | None:
     """Browse `rows` interactively. `columns` is the same `(header, kwargs)` spec `slab_table`
     takes; each row is `(item, cells)` with one markup string per column. `hint` names what
@@ -337,11 +338,17 @@ def browse(
 
     Quitting prints the top-level table (with `footer`) as a scrollback receipt. On a
     non-interactive stdout/stdin the static table is printed instead and None returned.
+
+    `receipt` swaps a different Page in for both of those static prints — for when the
+    interactive top level is a navigation aid (e.g. cards grouped by set) but the flat result
+    list is what scrollback and pipes should keep.
     """
     if not rows:
         return None
+    static = receipt or Page(columns, rows, title, note, hint, footer)
     if not _interactive_ok():
-        print_table(columns, rows, title=title, note=note, footer=footer)
+        print_table(static.columns, static.rows,
+                    title=static.title, note=static.note, footer=static.footer)
         return None
 
     root = Page(columns, rows, title, note, hint, footer, detail, sel=start)
@@ -374,6 +381,8 @@ def browse(
     if picked is not None:
         return picked
     # Quit: leave the classic table behind so the results live on in scrollback. It's the TOP
-    # level's table however deep the user was — that's the list they asked for.
-    print_table(root.columns, root.rows, title=root.title, note=root.note, footer=root.footer)
+    # level's table (or the `receipt` standing in for it) however deep the user was — that's
+    # the list they asked for.
+    print_table(static.columns, static.rows,
+                title=static.title, note=static.note, footer=static.footer)
     return None

{slab_cli-0.20.0 → slab_cli-0.22.0}/src/slab_cli/commands/catalog.py

@@ -41,13 +41,16 @@ def cmd_search(args: list[str]) -> None:
     Sort keys: year, card_number, numbered, subject, brand, set (prefix - for descending).
 
     Results are one row per CARD, however many parallels it has — a player with a 17-finish
-    rainbow would otherwise bury his other cards under one of them. In a terminal that list is
-    scrollable and drills down: Enter opens the card's printings (base + every parallel, with
-    print run and odds), Enter again opens that printing's market view, Esc climbs back one level
-    and q leaves. `--printings` flattens it back to one row per printing (finish, run, and odds
-    on every row) — what you want when the finish IS the thing you're scanning for, and the form
-    to pipe when a script wants every parallel. Piped output prints the plain table of whichever
-    shape you asked for; the row shape doesn't change just because output is a terminal.
+    rainbow would otherwise bury his other cards under one of them. In a terminal the browse is
+    set-first: results are grouped into the sets they belong to (even a subset like Young Guns
+    spans several products), Enter opens that set's cards, Enter again the highlighted card's
+    printings (base + every parallel, with print run and odds), Enter once more that printing's
+    market view — Esc climbs back one level, q leaves. When every result is from one set the
+    set level is skipped and the browse opens straight on its cards. `--printings` flattens it
+    back to one row per printing (finish, run, and odds on every row) — what you want when the
+    finish IS the thing you're scanning for, and the form to pipe when a script wants every
+    parallel. Piped output prints the plain one-row-per-card (or per-printing) table; the row
+    shape doesn't change just because output is a terminal.
     """
     if not args:
         args = [ask_text("Search cards:")]
@@ -110,7 +113,8 @@ def cmd_rainbow(args: list[str]) -> None:
     if len(args) == 1 and _UUID_RE.match(args[0]):
         card_uuid = args[0]
     else:
-        card = pick_card(" ".join(args) if args else None)
+        # Stop the picker at the card — this command's whole output IS the parallel step.
+        card = pick_card(" ".join(args) if args else None, printing=False)
         if card is None:
             return
         card_uuid = card.uuid

{slab_cli-0.20.0 → slab_cli-0.22.0}/src/slab_cli/commands/collection.py

@@ -20,6 +20,7 @@ from slab_schemas.enums import AcquisitionType, CopyStatus, CostCategory, grade_
 from ..client import ApiError, SlabClient
 from ..context import ctx
 from ..flags import COLLECTION_SEARCH_FLAGS, parse_flags
+from ..nav import BackStep, flow
 from ..paging import fetch_all_pages
 from ..picker import pick_card
 from ..display import (
@@ -75,12 +76,13 @@ class AddSession:
 
 def _search_and_select_card(session: AddSession) -> CardOut | None:
     """Find the exact card the user got, SUBJECT-FIRST: (1) search a player and pick them, (2) pick
-    the set they're in, then (3) pick the exact printing — base, parallel, insert, auto. Step 2 is
-    what stops a player who appears across many products from dumping into one undifferentiated list
-    (the set name also rides each row when the list still spans sets). When a break is in play every
-    search is scoped to that box (its release), so the set step auto-collapses and you only ever see
-    cards that could have come from what you opened. Shares the picker with the rest of the CLI; the
-    only add-specific bits are the next/first prompt and the box-scoped 'not found' message."""
+    the set they're in, (3) pick the card, then (4) the exact printing off its rainbow (base is a
+    single Enter). Step 2 is what stops a player who appears across many products from dumping into
+    one undifferentiated list (the set name also rides each row when the list still spans sets).
+    When a break is in play every search is scoped to that box (its release), so the set step
+    auto-collapses and you only ever see cards that could have come from what you opened. Shares
+    the picker with the rest of the CLI; the only add-specific bits are the next/first prompt and
+    the box-scoped 'not found' message."""
     prompt = "Search for next card (player):" if session.cards_added > 0 else "Search for a card (player):"
     not_found = (
         "No cards found in this box. Try a different player name."
@@ -245,31 +247,52 @@ def _submit_and_report(session: AddSession, card: CardOut, acq_cost: Decimal | N
 def _add_single_card(session: AddSession, card: CardOut | None = None) -> bool:
     """Run one add-card iteration. Returns True if the card was added, False if skipped/cancelled.
 
-    When `card` is given (e.g. from a chase-set missing-card walk) the catalog search is skipped and
-    that exact printing is used — you go straight to the acquisition details."""
+    The per-card sequence is a `nav.flow` — Esc at any detail step (cost, grades, serial, the
+    review confirm) goes back one step, and Esc past the first step skips this card. The picker
+    inside the first step is its own flow, so Esc also walks printing → card → set → player →
+    search text before falling out here.
+
+    When `card` is given (e.g. from a chase-set missing-card walk) the catalog search is skipped
+    and that exact printing is used — you go straight to the acquisition details."""
     # Decide how these cards were acquired (and the break/box) up front, so the search is scoped.
+    # Deliberately OUTSIDE the flow: it's batch-level state, and re-answering it per Esc would be
+    # worse than Esc simply skipping the card.
     _ensure_acquisition_context(session)
 
-    if card is None:
-        card = _search_and_select_card(session)
-    if card is None:
-        return False
+    def s_pick(st: dict) -> None:
+        picked = card if card is not None else _search_and_select_card(session)
+        if picked is None:
+            raise BackStep()
+        st["card"] = picked
+        console.print(f"\n  [bold]{format_card_summary(picked)}[/bold]\n")
 
-    console.print(f"\n  [bold]{format_card_summary(card)}[/bold]\n")
+    def s_cost(st: dict) -> None:
+        st["acq_cost"] = _per_card_cost(session)
 
-    acq_cost = _per_card_cost(session)
-    break_uuid = session.break_uuid
-    self_grade, grading_company, grade, cert_number = _collect_grade_details()
-    serial = _prompt_serial(card)
+    def s_grades(st: dict) -> None:
+        st["grades"] = _collect_grade_details()
 
-    _show_review(card, session, acq_cost, break_uuid, self_grade, grading_company, grade, serial)
+    def s_serial(st: dict) -> None:
+        st["serial"] = _prompt_serial(st["card"])
+
+    def s_review(st: dict) -> None:
+        self_grade, grading_company, grade, _cert = st["grades"]
+        _show_review(st["card"], session, st["acq_cost"], session.break_uuid,
+                     self_grade, grading_company, grade, st["serial"])
+        st["confirmed"] = confirm("Add this card?", default=True)
+
+    try:
+        st = flow([s_pick, s_cost, s_grades, s_serial, s_review])
+    except BackStep:
+        return False
 
-    if not confirm("Add this card?", default=True):
+    if not st["confirmed"]:
         console.print("[dim]Skipped.[/dim]\n")
         return False
 
-    _submit_and_report(session, card, acq_cost, break_uuid, self_grade,
-                       grading_company, grade, cert_number, serial)
+    self_grade, grading_company, grade, cert_number = st["grades"]
+    _submit_and_report(session, st["card"], st["acq_cost"], session.break_uuid, self_grade,
+                       grading_company, grade, cert_number, st["serial"])
     return True
 
 
@@ -277,11 +300,16 @@ def cmd_add(args: list[str]) -> None:
     """Add card(s) to your collection — interactive with batch support."""
     session = AddSession(client=ctx.client, collector=ctx.collector)
 
-    while True:
-        _add_single_card(session)
+    # Ctrl-C (or Esc at the "another?" prompt) ends the batch, not the receipt: fall through to
+    # the Done line so the user still sees what landed.
+    try:
+        while True:
+            _add_single_card(session)
 
-        if not confirm("Add another card?", default=True):
-            break
+            if not confirm("Add another card?", default=True):
+                break
+    except (KeyboardInterrupt, BackStep):
+        console.print()
 
     if session.cards_added > 0:
         console.print(f"[dim]Done — {session.cards_added} card(s) added.[/dim]")
@@ -623,8 +651,11 @@ def cmd_search(args: list[str]) -> None:
     Sort keys: acquired_date, acquisition_cost, numbered, year, card_number, brand, set,
     fmv, unrealized, roi (prefix - for descending).
 
-    In a terminal the results are a scrollable list — Enter drills into the highlighted
-    copy's market view, Esc climbs back. Piped output prints the plain table.
+    In a terminal the browse is set-first, same as `slab card search`: matches are grouped
+    into the sets they came from (with each set's copy count, cost basis, FMV, and gain/loss),
+    Enter opens that set's copies, Enter again the highlighted copy's market view — Esc climbs
+    back one level, q leaves. One-set results skip the set level. Piped output prints the plain
+    one-row-per-copy table.
     """
     if not args:
         total = ctx.client.search_collection(ctx.collector, CollectionSearchQuery(limit=1)).total

{slab_cli-0.20.0 → slab_cli-0.22.0}/src/slab_cli/commands/custom_sets.py

@@ -2,9 +2,10 @@
 
 from __future__ import annotations
 
-from InquirerPy import inquirer
 from InquirerPy.base.control import Choice
 
+from ..nav import inquirer
+
 from types import SimpleNamespace
 
 from slab_schemas.custom_sets import (
@@ -25,7 +26,7 @@ from ..display import (
     print_custom_set_detail,
 )
 from ..paging import fetch_all_pages
-from ..picker import search_and_pick_subject
+from ..picker import pick_card_with_subject, search_and_pick_subject
 from ..prompts import (
     ask_int_optional,
     ask_text,
@@ -35,7 +36,6 @@ from ..prompts import (
     select_dynamic_match,
     select_entry_kind,
     select_match_mode,
-    select_printing,
     select_visibility,
 )
 
@@ -93,17 +93,14 @@ def _pick_from_sets(sets: list[CustomSetOut], message: str) -> CustomSetOut | No
 
 
 def _search_and_select_card_for_set() -> tuple[str | None, str | None]:
-    """Search the catalog, pick a player, pick a printing. Returns (card_uuid, subject_name) or
-    (None, None). Uses the shared subject picker; the only chase-specific step is the summary print
-    and the (uuid, subject) return shape the batch loop wants."""
-    picked = search_and_pick_subject(None)
+    """Search the catalog, pick a player, narrow to a set (or all), pick the card, then the
+    exact printing off its rainbow — the shared picker flow (Esc steps back, Ctrl-C quits).
+    Returns (card_uuid, subject_name) or (None, None); the only chase-specific part is the
+    summary print and the (uuid, subject) return shape the batch loop wants."""
+    picked = pick_card_with_subject(None)
     if picked is None:
         return None, None
-    cards, subject = picked
-
-    card = select_printing(cards, subject)
-    if card is None:
-        return None, None
+    card, subject = picked
 
     console.print(f"\n  [bold]{format_card_summary(card)}[/bold]\n")
     return card.uuid, subject

{slab_cli-0.20.0 → slab_cli-0.22.0}/src/slab_cli/commands/pricing.py

@@ -20,11 +20,10 @@ from ..display import (
     render_set_market,
 )
 from ..paging import fetch_all_pages
-from ..picker import pick_card, search_and_pick_subject
+from ..picker import pick_card, pick_card_with_subject
 from ..prompts import (
     select_priced_card,
     select_set,
-    select_set_filter,
 )
 
 
@@ -38,32 +37,25 @@ def _optional_collector() -> str | None:
 
 
 def _pick_card(args: list[str]) -> CardOut | None:
-    """Price/comps selection: player → set (or all) → a card from the FMV-tagged list. Shares the
-    subject-first core (`search_and_pick_subject`) with every other picker, then adds the two
-    pricing-specific steps: the enriched search (each row carries its headline FMV + owned tag) and
-    a set-narrowing step before the FMV list. Returns the chosen card, or None if the user backed
-    out or nothing matched."""
-    picked = search_and_pick_subject(
+    """Price/comps selection: player → set (or all) → a card from the FMV-tagged list → the
+    exact printing off its rainbow. The shared picker flow (Esc steps back, Ctrl-C quits); the
+    one pricing-specific part is the enriched card list (each slot row carries its headline FMV +
+    owned tag) in place of the plain card pick. Returns the chosen printing, or None if the user
+    backed out or nothing matched."""
+    picked = pick_card_with_subject(
         " ".join(args) if args else None,
         collector=_optional_collector(),
         include_market=True,
+        card_step=select_priced_card,
     )
-    if picked is None:
-        return None
-    cards, subject = picked
-
-    # Narrow to a set (auto-skips when the player only appears in one set).
-    slug = select_set_filter(cards)
-    if slug:
-        cards = [c for c in cards if c.set_slug == slug]
-
-    return select_priced_card(cards, subject, show_set=not slug)
+    return picked[0] if picked else None
 
 
 def cmd_price(args: list[str]) -> None:
-    """Price a player's cards: pick the player, narrow to a set (or all), see every printing with
-    its FMV (● = you own it), then drill into one for the full market view. Catalog-level — no
-    ownership required, but owned copies are tagged when a collector is configured."""
+    """Price a player's cards: pick the player, narrow to a set (or all), see each card with its
+    headline FMV (● = you own it), pick one, then the exact printing off its rainbow for the full
+    market view. Catalog-level — no ownership required, but owned copies are tagged when a
+    collector is configured."""
     card = _pick_card(args)
     if card is None:
         return
@@ -348,9 +340,10 @@ def cmd_history(args: list[str]) -> None:
       slab card history bedard
       slab card history bedard --days 90 --daily
       slab card history mcdavid --monthly"""
-    from InquirerPy import inquirer
     from InquirerPy.base.control import Choice
 
+    from ..nav import inquirer
+
     query, interval, days = _history_options(args)
     card = pick_card(" ".join(query) if query else None)
     if card is None:
@@ -389,9 +382,10 @@ def cmd_set_history(args: list[str]) -> None:
     Examples:
       slab set history allure
       slab set history "series 1" --days 180 --weekly"""
-    from InquirerPy import inquirer
     from InquirerPy.base.control import Choice
 
+    from ..nav import inquirer
+
     query, interval, days = _history_options(args)
 
     sets = _fetch_all_sets()

{slab_cli-0.20.0 → slab_cli-0.22.0}/src/slab_cli/display.py

@@ -125,6 +125,20 @@ PRINTING_COLUMNS = [
     ("Odds", {"style": "slab.dim"}),
 ]
 
+# The set-first browse: search results bucketed into the sets they came from, one row per set.
+# Even a subset query wants this level — Young Guns spans several products.
+SET_GROUP_COLUMNS = [
+    ("Set", {"style": "slab.value"}),
+    ("Brand", {}),
+    ("Season", {"style": "slab.dim"}),
+    ("Cards", {"justify": "right", "style": "slab.accent"}),
+]
+
+# Inside one set the Set column is a constant (it's the page title), so the in-set card list
+# drops it. Derived from SLOT_COLUMNS so the two shapes can't drift.
+_SET_COL = next(i for i, (header, _) in enumerate(SLOT_COLUMNS) if header == "Set")
+IN_SET_SLOT_COLUMNS = [col for i, col in enumerate(SLOT_COLUMNS) if i != _SET_COL]
+
 
 def card_cells(c: CardOut) -> list[str]:
     """One catalog card as its CARD_COLUMNS cells."""
@@ -156,6 +170,25 @@ def printing_cells(c: CardOut) -> list[str]:
     ]
 
 
+def in_set_slot_cells(c: CardOut) -> list[str]:
+    """`slot_cells` without the Set column — for the per-set card list, where Set is the title."""
+    return [cell for i, cell in enumerate(slot_cells(c)) if i != _SET_COL]
+
+
+def group_by_set(cards: list[CardOut]) -> list[list[CardOut]]:
+    """Search results bucketed by set, in first-seen order — the top level of a card browse."""
+    groups: dict[str, list[CardOut]] = {}
+    for c in cards:
+        groups.setdefault(c.set_slug or c.set_name or "", []).append(c)
+    return list(groups.values())
+
+
+def set_group_cells(cards: list[CardOut]) -> list[str]:
+    """One result-set bucket as its SET_GROUP_COLUMNS cells (any card carries the set fields)."""
+    rep = cards[0]
+    return [rep.set_name or "Unknown set", rep.brand or "", rep.season or "", str(len(cards))]
+
+
 def card_title(c: CardOut) -> str:
     """A single card named for a heading: '#86 Paul Coffey — 2021-22 Stature'."""
     subjects = ", ".join(s.name for s in c.subjects) or "—"
@@ -166,10 +199,14 @@ def browse_cards(result: CardSearchResult, *, detail=None, printings=None) -> Ca
     """Browse a card search. `detail` (a `CardOut -> None` renderer) is what Enter opens on a
     PRINTING; Esc climbs back. Static table on non-interactive output.
 
-    With `printings` (a `CardOut -> list[CardOut]` loader, i.e. the parallels endpoint) the list is
-    one row per card and Enter opens that card's printings as a nested list, whose Enter runs
-    `detail` — so a search for a player reads as his cards, not as every finish of every card.
-    Without it, every printing is its own row and Enter runs `detail` straight away."""
+    With `printings` (a `CardOut -> list[CardOut]` loader, i.e. the parallels endpoint) the browse
+    goes set-first: results grouped into the sets they came from, Enter opens that set's cards,
+    Enter again the card's printings, whose Enter runs `detail` — so a search for a player reads
+    as the sets he's in, then his cards in one, never as every finish of every card. When every
+    result is from a single set the set level would be a one-row picker, so it's skipped and the
+    browse opens on that set's cards. The static table (pipes, and the quit receipt) stays the
+    flat one-row-per-card list either way. Without `printings`, every printing is its own row and
+    Enter runs `detail` straight away."""
     if not result.items:
         console.print("[slab.dim]No cards found.[/]")
         return None
@@ -191,10 +228,29 @@ def browse_cards(result: CardSearchResult, *, detail=None, printings=None) -> Ca
             hint="market view", detail=detail,
         )
 
+    def cards_page(cards: list[CardOut]) -> Page:
+        rep = cards[0]
+        return Page(
+            IN_SET_SLOT_COLUMNS, [(c, in_set_slot_cells(c)) for c in cards],
+            title=rep.set_name or "Unknown set",
+            note=f"{len(cards)} card{'' if len(cards) == 1 else 's'}",
+            hint="printings", detail=rainbow,
+        )
+
+    flat = Page(SLOT_COLUMNS, [(c, slot_cells(c)) for c in result.items],
+                title="Cards", note=f"{result.total} total", footer=footer)
+
+    groups = group_by_set(result.items)
+    if len(groups) == 1:
+        page = cards_page(groups[0])
+        return browse(
+            page.columns, page.rows, title=page.title, note=page.note,
+            hint=page.hint, footer=footer, detail=rainbow, receipt=flat,
+        )
     return browse(
-        SLOT_COLUMNS, [(c, slot_cells(c)) for c in result.items],
-        title="Cards", note=f"{result.total} total", hint="printings",
-        footer=footer, detail=rainbow,
+        SET_GROUP_COLUMNS, [(g, set_group_cells(g)) for g in groups],
+        title="Cards", note=f"{result.total} total · {len(groups)} sets",
+        hint="cards", footer=footer, detail=cards_page, receipt=flat,
     )
 
 
@@ -258,6 +314,21 @@ COLLECTION_COLUMNS = [
     ("Gain/Loss", {"justify": "right"}),
 ]
 
+# The collection's set-first level: one row per set you hold copies from, with that set's share
+# of the money — the same subject → set → card order the catalog browse and pickers use.
+COLLECTION_SET_GROUP_COLUMNS = [
+    ("Set", {"style": "slab.value"}),
+    ("Copies", {"justify": "right", "style": "slab.accent"}),
+    ("Cost Basis", {"justify": "right"}),
+    ("FMV", {"justify": "right"}),
+    ("Gain/Loss", {"justify": "right"}),
+]
+
+# Same derivation as the catalog's in-set columns: inside one set's page the Set column is the
+# title, so it drops out of the rows.
+_COLL_SET_COL = next(i for i, (header, _) in enumerate(COLLECTION_COLUMNS) if header == "Set")
+IN_SET_COLLECTION_COLUMNS = [col for i, col in enumerate(COLLECTION_COLUMNS) if i != _COLL_SET_COL]
+
 
 def collection_cells(cp) -> list[str]:
     """One owned copy as its COLLECTION_COLUMNS cells."""
@@ -276,6 +347,42 @@ def collection_cells(cp) -> list[str]:
     return [card_num, subjects, set_name, finish, grade, basis, fmv, gain]
 
 
+def in_set_collection_cells(cp) -> list[str]:
+    """`collection_cells` without the Set column — for the per-set copy list."""
+    return [cell for i, cell in enumerate(collection_cells(cp)) if i != _COLL_SET_COL]
+
+
+def group_copies_by_set(copies) -> list[list]:
+    """Collection results bucketed by their card's set, in first-seen order. Copies with no
+    linked catalog card share one bucket (they have no set to claim)."""
+    groups: dict[str, list] = {}
+    for cp in copies:
+        card = cp.card
+        key = (card.set_slug or card.set_name or "") if card else ""
+        groups.setdefault(key, []).append(cp)
+    return list(groups.values())
+
+
+def collection_set_group_cells(copies) -> list[str]:
+    """One set bucket of owned copies as its COLLECTION_SET_GROUP_COLUMNS cells. The money
+    columns sum whatever the copies report (a copy without a value contributes nothing, same as
+    the dashboard's totals)."""
+    rep = next((cp.card for cp in copies if cp.card), None)
+    count = sum(cp.quantity or 1 for cp in copies)
+    bases = [cp.cost_basis for cp in copies if cp.cost_basis is not None]
+    fmvs = [cp.market.fair_market_value for cp in copies
+            if cp.market and cp.market.fair_market_value is not None]
+    gains = [cp.market.unrealized_gain_loss for cp in copies
+             if cp.market and cp.market.unrealized_gain_loss is not None]
+    return [
+        (rep.set_name if rep and rep.set_name else "[slab.dim]No linked set[/]"),
+        str(count),
+        money(sum(bases)) if bases else "[slab.dim]—[/]",
+        f"[slab.foil]{money(sum(fmvs))}[/]" if fmvs else "[slab.dim]—[/]",
+        signed_money(sum(gains)) if gains else "[slab.dim]—[/]",
+    ]
+
+
 def print_collection_summary(result: CollectionResult) -> None:
     """The financial totals line under a collection search — from the server's summary block."""
     if not result.summary:
@@ -297,20 +404,42 @@ def print_collection_summary(result: CollectionResult) -> None:
 
 
 def browse_collection(result: CollectionResult, *, detail=None) -> None:
-    """Browse a collection search. With `detail` (a copy -> None renderer), Enter drills into
-    the copy's market view; Esc climbs back. Static table on non-interactive output."""
+    """Browse a collection search, set-first like the catalog browse: copies grouped into the
+    sets they came from (with each set's copy count and money rollup), Enter opens that set's
+    copies, Enter again the copy's market view via `detail` (a copy -> None renderer); Esc climbs
+    back a level. A single-set result skips the one-row set picker and opens on its copies. The
+    static table (pipes, and the quit receipt) stays the flat one-row-per-copy list."""
     if not result.items:
         console.print("[dim]No cards in your collection matching that search.[/dim]")
         if result.total == 0:
             console.print("  [dim]Use `slab collection add` to start cataloging cards.[/dim]")
         return
     matches = f"{result.total} match{'' if result.total == 1 else 'es'}"
+    footer = _shown_footer(len(result.items), result.total,
+                           "narrow your search, or `slab export` for the full list.")
+
+    def copies_page(copies) -> Page:
+        rep = next((cp.card for cp in copies if cp.card), None)
+        return Page(
+            IN_SET_COLLECTION_COLUMNS, [(cp, in_set_collection_cells(cp)) for cp in copies],
+            title=(rep.set_name if rep and rep.set_name else "No linked set"),
+            note=f"{len(copies)} cop{'y' if len(copies) == 1 else 'ies'}",
+            hint="market view", detail=detail,
+        )
+
+    flat = Page(COLLECTION_COLUMNS, [(cp, collection_cells(cp)) for cp in result.items],
+                title="Collection", note=matches, footer=footer)
+
+    groups = group_copies_by_set(result.items)
+    if len(groups) == 1:
+        page = copies_page(groups[0])
+        browse(page.columns, page.rows, title=page.title, note=page.note,
+               hint=page.hint, footer=footer, detail=detail, receipt=flat)
+        return
     browse(
-        COLLECTION_COLUMNS, [(cp, collection_cells(cp)) for cp in result.items],
-        title="Collection", note=matches, hint="market view",
-        footer=_shown_footer(len(result.items), result.total,
-                             "narrow your search, or `slab export` for the full list."),
-        detail=detail,
+        COLLECTION_SET_GROUP_COLUMNS, [(g, collection_set_group_cells(g)) for g in groups],
+        title="Collection", note=f"{matches} · {len(groups)} sets",
+        hint="copies", footer=footer, detail=copies_page, receipt=flat,
     )
 
 

{slab_cli-0.20.0 → slab_cli-0.22.0}/src/slab_cli/help.py

@@ -101,6 +101,10 @@ def render_root_help() -> None:
         console.print(heading(group.name, group.blurb))
         console.print(_group_table(group))
         console.print()
+    console.print(Text.from_markup(
+        "  [slab.label]Keys[/]     [slab.dim]In any interactive flow: "
+        "Esc goes back a step · Ctrl-C cancels the command[/]"
+    ))
     console.print(Text.from_markup(f"  [slab.label]Config[/]   [slab.dim]{_CONFIG}[/]"))
     # The installed version, right where people look for it. Whether it's the NEWEST version is the
     # update nudge's job (printed after any command from a cached daily check) — not restated here.

{slab_cli-0.20.0 → slab_cli-0.22.0}/src/slab_cli/main.py

@@ -18,6 +18,7 @@ from .context import MissingCollector
 from .display import console
 from .flags import FlagError
 from .help import render_command_help, render_group_help, render_root_help
+from .nav import BackStep
 
 _HELP_FLAGS = ("-h", "--help", "help")
 _VERSION_FLAGS = ("-V", "--version")
@@ -95,7 +96,9 @@ def _dispatch(args: list[str]) -> int:
     *any* path — success, cancel, or error — exactly once."""
     try:
         return _run(args)
-    except KeyboardInterrupt:
+    except (KeyboardInterrupt, BackStep):
+        # The two standard leave-the-flow actions (nav.py): Ctrl-C anywhere, or Esc backing out
+        # past a flow's first step. Both end the command the same clean way.
         console.print("\n[dim]Cancelled.[/dim]")
         return 0
     except FlagError as e:

slab_cli-0.22.0/src/slab_cli/nav.py

@@ -0,0 +1,112 @@
+"""The CLI's standard step navigation — ONE contract for every interactive flow.
+
+Two actions work at EVERY prompt, the same keys the browse table already uses:
+
+* **Esc — back one step.** Raises `BackStep`. Inside a `flow(...)` it returns to the previous
+  step that actually asked something (steps that auto-resolved — a lone match, a derived value —
+  are stepped over, so Esc never bounces off an invisible step). At the first step, or in a
+  prompt that isn't part of a flow, it bubbles up: the command cancels cleanly ("Cancelled.",
+  handled in `main._dispatch`) or an enclosing loop treats it as "skip this one".
+* **Ctrl-C — quit.** InquirerPy raises KeyboardInterrupt, which every layer already treats as
+  "leave the whole command" (dispatch prints "Cancelled."; batch loops may catch it to print
+  their summary first). Nothing here intercepts it — quit must always win.
+
+`q` is deliberately NOT a prompt-level key: in fuzzy filters and text inputs the letter q is
+input. The browse table (browse.py) keeps its q-to-quit because its lists never type; Esc/Ctrl-C
+mean the same thing there, so the two systems feel identical.
+
+Mechanics: `inquirer` below is a drop-in proxy for `InquirerPy.inquirer` whose prompts execute
+through the nav layer — import it from here instead of InquirerPy and every prompt gains the
+contract with no per-call-site changes. `flow(steps)` is the step runner commands use to make
+Esc rewind rather than cancel.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from InquirerPy import inquirer as _inquirer
+
+
+class BackStep(Exception):
+    """The user pressed Esc: go back one step. `flow` catches it to rewind; uncaught, it means
+    'back out of this whole interaction' and dispatch turns it into a clean cancel."""
+
+
+# Counts prompts actually SHOWN (not auto-resolved). `flow` reads it around each step to learn
+# which steps interacted — that's what makes Esc skip over auto-resolved steps without every
+# step having to declare itself.
+_prompts_shown = 0
+
+
+def prompt_shown() -> None:
+    """Record that a prompt was displayed. Called by the executor below; test doubles and
+    non-InquirerPy prompts (if any grow) call it to participate in flow()'s back-tracking."""
+    global _prompts_shown
+    _prompts_shown += 1
+
+
+def _nav_execute(prompt) -> Any:
+    """Execute an InquirerPy prompt with the standard navigation attached: Esc raises BackStep,
+    Ctrl-C propagates as KeyboardInterrupt (InquirerPy's default)."""
+    prompt_shown()
+    backed = False
+
+    @prompt.register_kb("escape")
+    def _(event):  # noqa: ANN001 - prompt_toolkit event
+        nonlocal backed
+        backed = True
+        event.app.exit(result=None)
+
+    result = prompt._nav_original_execute()
+    if backed:
+        raise BackStep()
+    return result
+
+
+class _NavInquirer:
+    """`InquirerPy.inquirer`, with the nav contract attached to every prompt it builds."""
+
+    def __getattr__(self, name: str):
+        factory = getattr(_inquirer, name)
+
+        def build(*args, **kwargs):
+            prompt = factory(*args, **kwargs)
+            prompt._nav_original_execute = prompt.execute
+            prompt.execute = lambda: _nav_execute(prompt)
+            return prompt
+
+        return build
+
+
+inquirer = _NavInquirer()
+
+
+def flow(steps: list[Callable[[dict], None]], state: dict | None = None) -> dict:
+    """Run `steps` in order over a shared `state` dict, with Esc stepping backward.
+
+    Each step reads/writes `state` and prompts as it likes. When a step raises BackStep, the
+    flow resumes at the nearest EARLIER step that actually showed a prompt on its last run —
+    auto-resolved steps (nothing to re-answer) are skipped on the way back, then re-run on the
+    way forward so derived state stays fresh. BackStep at the first interactive step propagates:
+    the caller decides what backing out of the whole flow means (usually `return None`).
+    KeyboardInterrupt is never caught — quit always exits the flow. Returns `state`.
+    """
+    state = state if state is not None else {}
+    asked = [False] * len(steps)
+    i = 0
+    while i < len(steps):
+        before = _prompts_shown
+        try:
+            steps[i](state)
+        except BackStep:
+            j = i - 1
+            while j >= 0 and not asked[j]:
+                j -= 1
+            if j < 0:
+                raise
+            i = j
+            continue
+        asked[i] = _prompts_shown > before
+        i += 1
+    return state

slab_cli-0.22.0/src/slab_cli/picker.py

@@ -0,0 +1,178 @@
+"""One subject-first card picker for the whole CLI.
+
+Every command that resolves a human query to a specific catalog card (`card parallels`,
+`card price`/`comps`, `card history`, `collection add`, `chase add`) does it the same way:
+search a player, pick the player, narrow to a set (or all — auto-skipped when there's only
+one), pick the CARD (one row per checklist slot), then pick the exact printing off that card's
+rainbow (base is the default) — the same subject → set → card → parallel drill the browse table
+gives search results. This module is that flow, once, built on `nav.flow` so the standard keys
+work at every step: **Esc backs up one step** (printing → card → set → player → search text —
+auto-resolved steps are stepped over) and **Ctrl-C quits the command**. Callers that need a
+different card list (pricing's FMV-tagged rows) pass `card_step`; ones that need the subject
+too use `pick_card_with_subject`.
+
+The search is COLLAPSED and PAGED: one row per slot (`collapse_parallels=True`), fetched past
+the server's 200-per-request cap to completion. Both halves matter — a prolific player has
+thousands of printings (McDavid: 1,500+), so a single uncollapsed page silently dropped most of
+his sets and made catalogued cards unfindable here while `card search` showed them fine. The
+rainbow is fetched per picked card instead, exactly like the break-fill walk.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from slab_schemas.cards import CardOut, CardSearchQuery
+
+from .context import ctx
+from .nav import BackStep, flow
+from .paging import fetch_all_pages
+from .prompts import (
+    ask_text,
+    select_printing,
+    select_printing_for_slot,
+    select_set_filter,
+    select_subject,
+)
+from .theme import console
+
+# Slots fetched per search, not printings — a safety bound, far above any real player's card count.
+_SLOT_CAP = 5000
+
+
+def _search_slots(q: str, **search_kwargs) -> list[CardOut]:
+    """Fetch EVERY slot matching a subject query (collapsed, paged — see module docstring)."""
+    slots, _ = fetch_all_pages(
+        lambda limit, offset: ctx.client.search_cards(CardSearchQuery(
+            subject=q, collapse_parallels=True, limit=limit, offset=offset, **search_kwargs
+        )),
+        cap=_SLOT_CAP,
+    )
+    return slots
+
+
+def _subject_steps(
+    query: str | None, prompt: str, not_found: str, search_kwargs: dict,
+) -> list[Callable[[dict], None]]:
+    """The shared first three steps of every picker flow: ask/take the query, fetch all slots,
+    pick the player. Leaves `q`, `slots`, `subject`, and `cards` (the subject's slots) in the
+    flow state. An empty search raises BackStep — back to the query prompt to retype (or out of
+    the flow, when the query came from argv and there's nothing to return to)."""
+
+    def s_query(st: dict) -> None:
+        st["q"] = query if query else ask_text(prompt)
+
+    def s_fetch(st: dict) -> None:
+        st["slots"] = _search_slots(st["q"], **search_kwargs)
+        if not st["slots"]:
+            console.print(f"[yellow]{not_found}[/yellow]")
+            raise BackStep()
+
+    def s_subject(st: dict) -> None:
+        subject = select_subject(st["slots"])
+        if subject is None:
+            raise BackStep()
+        st["subject"] = subject
+        st["cards"] = [c for c in st["slots"] if any(s.name == subject for s in c.subjects)]
+
+    return [s_query, s_fetch, s_subject]
+
+
+def search_and_pick_subject(
+    query: str | None,
+    *,
+    prompt: str = "Search for a card (player):",
+    not_found: str = "No cards found.",
+    **search_kwargs,
+) -> tuple[list[CardOut], str] | None:
+    """The subject-first core alone: resolve a query to ``(that subject's card slots, subject)``
+    — for callers that stop at the player (chase player-slots). Returns ``None`` when the user
+    backs out of the whole thing; Esc inside steps back (player pick → search text)."""
+    try:
+        st = flow(_subject_steps(query, prompt, not_found, search_kwargs))
+    except BackStep:
+        return None
+    return st["cards"], st["subject"]
+
+
+def narrow_to_set(cards: list[CardOut]) -> tuple[list[CardOut], bool]:
+    """The shared set step: offer to narrow a cross-set card list to one set — "All sets" keeps
+    everything, and the prompt auto-skips when the list is already a single set. Returns the
+    (possibly narrowed) cards plus whether they still span sets: the ``show_set`` every card
+    picker takes."""
+    slug = select_set_filter(cards)  # auto-returns "" (all) when the player is in only one set
+    if slug:
+        cards = [c for c in cards if c.set_slug == slug]
+    return cards, len({c.set_slug for c in cards}) > 1
+
+
+def pick_printing_of(card: CardOut) -> CardOut | None:
+    """The final parallel step: fetch the picked card's whole rainbow and choose the exact
+    printing — base is the default, so the common case is a single Enter, and a slot with no
+    parallels auto-selects. Works from any printing (`get_parallels` resolves the slot's base)."""
+    return select_printing_for_slot(ctx.client.get_parallels(card.uuid))
+
+
+def pick_card_with_subject(
+    query: str | None,
+    *,
+    prompt: str = "Search for a card (player):",
+    not_found: str = "No cards found.",
+    narrow_set: bool = True,
+    printing: bool = True,
+    card_step: Callable[..., CardOut | None] = select_printing,
+    **search_kwargs,
+) -> tuple[CardOut, str] | None:
+    """The full picker flow — player → set → card → parallel — returning ``(card, subject)``,
+    or ``None`` if nothing matched or the user backed all the way out. Esc at any step returns
+    to the previous one (auto-resolved steps are skipped).
+
+    The set step is the default because a player who appears across many products shouldn't be
+    dumped into one undifferentiated list (and it auto-skips when everything is one set anyway).
+    Pass ``narrow_set=False`` only when the search is already scoped to a single release (e.g.
+    filling a break). ``printing=False`` stops at the card — for callers that resolve the whole
+    rainbow themselves (`card parallels`). ``card_step`` swaps the card list for a variant with
+    the same ``(cards, subject, show_set=...)`` signature (pricing's FMV-tagged list)."""
+
+    def s_set(st: dict) -> None:
+        if narrow_set:
+            st["in_set"], st["show_set"] = narrow_to_set(st["cards"])
+        else:
+            st["in_set"] = st["cards"]
+            st["show_set"] = len({c.set_slug for c in st["cards"]}) > 1
+
+    def s_card(st: dict) -> None:
+        card = card_step(st["in_set"], st["subject"], show_set=st["show_set"])
+        if card is None:
+            raise BackStep()
+        st["card"] = card
+
+    def s_printing(st: dict) -> None:
+        picked = pick_printing_of(st["card"]) if printing else st["card"]
+        if picked is None:
+            raise BackStep()
+        st["picked"] = picked
+
+    steps = _subject_steps(query, prompt, not_found, search_kwargs) + [s_set, s_card, s_printing]
+    try:
+        st = flow(steps)
+    except BackStep:
+        return None
+    return st["picked"], st["subject"]
+
+
+def pick_card(
+    query: str | None,
+    *,
+    prompt: str = "Search for a card (player):",
+    not_found: str = "No cards found.",
+    narrow_set: bool = True,
+    printing: bool = True,
+    **search_kwargs,
+) -> CardOut | None:
+    """The common case: `pick_card_with_subject`, returning just the chosen card."""
+    picked = pick_card_with_subject(
+        query, prompt=prompt, not_found=not_found,
+        narrow_set=narrow_set, printing=printing, **search_kwargs,
+    )
+    return picked[0] if picked else None

{slab_cli-0.20.0 → slab_cli-0.22.0}/src/slab_cli/prompts.py

@@ -10,9 +10,10 @@ from datetime import date
 from decimal import Decimal, InvalidOperation
 from typing import Protocol
 
-from InquirerPy import inquirer
 from InquirerPy.base.control import Choice
 
+from .nav import inquirer  # the nav proxy: every prompt gains Esc=back / Ctrl-C=quit
+
 from slab_schemas.cards import CardOut, SetOut, SetSearchResult
 from slab_schemas.collection import (
     BreakOut,
@@ -156,10 +157,11 @@ def walk_prompt(card: CardOut, position: tuple[int, int]) -> tuple[str, str | No
 
 
 def select_printing(cards: list[CardOut], subject: str, show_set: bool = False) -> CardOut | None:
-    """Subject-first step 2: pick the exact card for the chosen player — any printing (base,
-    parallel, insert, auto). Auto-selects when there's only one. `show_set` prepends the set name
-    to each row — used when the list spans multiple sets (e.g. the player wasn't narrowed to one
-    set), so you can tell a 2023-24 Young Guns from a 2024-25 one at a glance."""
+    """Subject-first card step: pick WHICH CARD for the chosen player — one row per checklist
+    slot (the picker searches collapsed), its parallels chosen next via `pick_printing_of` /
+    `select_printing_for_slot`. Auto-selects when there's only one. `show_set` prepends the set
+    name to each row — used when the list spans multiple sets (e.g. the player wasn't narrowed
+    to one set), so you can tell a 2023-24 Young Guns from a 2024-25 one at a glance."""
     if not cards:
         return None
     if len(cards) == 1:
@@ -176,7 +178,7 @@ def select_printing(cards: list[CardOut], subject: str, show_set: bool = False)
 
     choices = [Choice(value=c, name=label(c)) for c in cards]
     return inquirer.fuzzy(
-        message=f"Which card? — {subject} ({len(cards)} printings — type to filter):",
+        message=f"Which card? — {subject} ({len(cards)} cards — type to filter):",
         choices=choices,
         max_height="70%",
     ).execute()

slab_cli-0.20.0/src/slab_cli/picker.py

@@ -1,78 +0,0 @@
-"""One subject-first card picker for the whole CLI.
-
-Five commands (`card parallels`, `card price`/`comps`, `card history`, `collection add`,
-`chase add`) all resolve a human query to a specific catalog card the same way: search a player,
-pick the player, then pick the exact printing among that player's cards. This module is that flow,
-once. Callers that need a different *final* step (an FMV-tagged list, a set-narrowing step, a tuple
-return) build on `search_and_pick_subject`; the common case is `pick_card`.
-"""
-
-from __future__ import annotations
-
-from slab_schemas.cards import CardOut, CardSearchQuery
-
-from .context import ctx
-from .prompts import ask_text, select_printing, select_set_filter, select_subject
-from .theme import console
-
-
-def search_and_pick_subject(
-    query: str | None,
-    *,
-    prompt: str = "Search for a card (player):",
-    not_found: str = "No cards found.",
-    limit: int = 200,
-    **search_kwargs,
-) -> tuple[list[CardOut], str] | None:
-    """The shared subject-first core: resolve a query to ``(that subject's cards, subject name)``.
-
-    ``query`` is the search text; when falsy the user is prompted with ``prompt``. Extra
-    ``search_kwargs`` (e.g. ``release=[...]`` to scope to a box, ``include_market=True``,
-    ``collector=...``) pass straight through to ``CardSearchQuery``. Returns ``None`` if nothing
-    matched (prints ``not_found``) or the user backed out of the player pick — so the caller only
-    ever gets a non-empty card list plus the chosen subject.
-    """
-    q = query if query else ask_text(prompt)
-    result = ctx.client.search_cards(CardSearchQuery(subject=q, limit=limit, **search_kwargs))
-    if not result.items:
-        console.print(f"[yellow]{not_found}[/yellow]")
-        return None
-
-    subject = select_subject(result.items)
-    if subject is None:
-        return None
-
-    cards = [c for c in result.items if any(s.name == subject for s in c.subjects)]
-    return cards, subject
-
-
-def pick_card(
-    query: str | None,
-    *,
-    prompt: str = "Search for a card (player):",
-    not_found: str = "No cards found.",
-    limit: int = 200,
-    narrow_set: bool = False,
-    **search_kwargs,
-) -> CardOut | None:
-    """The common case: search a player, pick them, pick the exact printing. Returns the chosen
-    card, or ``None`` if nothing matched or the user backed out at any step.
-
-    With ``narrow_set=True`` an extra step lets you pick the set (or "all sets") after the player —
-    the same player → set → card flow the pricing commands use — so a player who appears across many
-    products isn't dumped into one undifferentiated list. The set name is shown on each row whenever
-    the (post-narrowing) list still spans more than one set."""
-    picked = search_and_pick_subject(
-        query, prompt=prompt, not_found=not_found, limit=limit, **search_kwargs
-    )
-    if picked is None:
-        return None
-    cards, subject = picked
-
-    if narrow_set:
-        slug = select_set_filter(cards)  # auto-returns "" (all) when the player is in only one set
-        if slug:
-            cards = [c for c in cards if c.set_slug == slug]
-
-    show_set = len({c.set_slug for c in cards}) > 1
-    return select_printing(cards, subject, show_set=show_set)