fix: restore htmx pagination and seed theme defaults

.env.example

@@ -13,7 +13,7 @@
 # HOST=0.0.0.0                       # Uvicorn bind host (only when APP_MODE=web).
 # PORT=8080                          # Uvicorn port.
 # WORKERS=1                          # Uvicorn worker count.
-APP_VERSION=v2.3.1                 # Matches dockerhub compose.
+APP_VERSION=v2.3.2                 # Matches dockerhub compose.
 
 ############################
 # Theming
@@ -46,18 +46,18 @@ WEB_THEME_PICKER_DIAGNOSTICS=0      # 1=enable uncapped synergies, diagnostics f
 ############################
 # Random Modes (alpha)
 ############################
-# RANDOM_MODES=1                     # Enable backend random build endpoints
-# RANDOM_UI=1                        # Show Surprise/Reroll/Share controls in UI
-# RANDOM_MAX_ATTEMPTS=5              # Cap retry attempts for constrained random builds
+RANDOM_MODES=1                     # Enable backend random build endpoints
+RANDOM_UI=1                        # Show Surprise/Reroll/Share controls in UI
+RANDOM_MAX_ATTEMPTS=5              # Cap retry attempts for constrained random builds
 # RANDOM_TIMEOUT_MS=5000             # Per-attempt timeout (ms)
 # HEADLESS_RANDOM_MODE=1             # Force headless runner to invoke random flow instead of scripted build
 # RANDOM_THEME=Treasure              # Legacy single-theme alias (maps to primary theme if others unset)
 # RANDOM_PRIMARY_THEME=Treasure      # Primary theme slug (case-insensitive)
 # RANDOM_SECONDARY_THEME=Artifacts   # Secondary theme slug
 # RANDOM_TERTIARY_THEME=Tokens       # Tertiary theme slug
-# RANDOM_AUTO_FILL=1                 # Auto-fill missing secondary/tertiary slots
-# RANDOM_AUTO_FILL_SECONDARY=1       # Explicit secondary auto-fill override (fallback from RANDOM_AUTO_FILL)
-# RANDOM_AUTO_FILL_TERTIARY=1        # Explicit tertiary auto-fill override (fallback from RANDOM_AUTO_FILL)
+RANDOM_AUTO_FILL=1                 # Auto-fill missing secondary/tertiary slots
+RANDOM_AUTO_FILL_SECONDARY=1       # Explicit secondary auto-fill override (fallback from RANDOM_AUTO_FILL)
+RANDOM_AUTO_FILL_TERTIARY=1        # Explicit tertiary auto-fill override (fallback from RANDOM_AUTO_FILL)
 # RANDOM_STRICT_THEME_MATCH=0        # Require strict commander theme matches
 # RANDOM_CONSTRAINTS=                # Inline JSON or path to JSON constraints for random selection
 # RANDOM_CONSTRAINTS_PATH=           # Alternate path-based constraints override (takes precedence if set)

.gitignore

@@ -22,7 +22,8 @@ logs/perf/*
 deck_files/
 config/themes/catalog/
 !config/card_lists/*.json
-!config/themes/*.json
+!config/themes/*.yml
+config/themes/theme_list.json
 !config/deck.json
 !test_exclude_cards.txt
 !test_include_exclude_config.json

CHANGELOG.md

@@ -22,6 +22,11 @@ This format follows Keep a Changelog principles and aims for Semantic Versioning
 ### Fixed
 - _No changes yet._
 
+## [2.3.2] - 2025-09-30
+### Fixed
+- Theme catalog pagination reprocesses HTMX fragments after Ajax loads so the “Next” button behaves correctly in the picker and simple catalog views.
+- Docker entrypoint now seeds the default `config/themes` files (e.g., `synergy_pairs.yml`, `theme_clusters.yml`, `theme_whitelist.yml`) into mounted volumes so Docker Hub images start with the expected theme catalog baseline.
+
 ## [2.3.1] - 2025-09-29
 ### Added
 - Headless runner parity: added `--random-mode` and accompanying `--random-*` flags to mirror the web Surprise/Reroll builder (multi-theme inputs, auto-fill overrides, deterministic seeds, constraints, and optional JSON payload export).

RELEASE_NOTES_TEMPLATE.md

@@ -1,126 +1,9 @@
 # MTG Python Deckbuilder ${VERSION}
 
 ## Summary
-- Hardened theme catalog schema to accept optional IDs and refreshed the preview performance baseline to keep CI checks green.
-- CI updates install the missing `httpx` dependency and run pytest through `python -m` to ensure the web stack tests import the local package correctly.
-- Fast-path catalog validation now tolerates empty synergy lists while still flagging missing fields or non-string entries.
-- Committed deterministic CSV fixtures under `csv_files/testdata` so CI random-mode checks have a stable dataset.
-- Owned Cards library tiles are larger, virtualization only kicks in for very large libraries, and popovers no longer show empty role pills.
-- File setup now keeps Hero creature type cards instead of filtering them with the non-Commander-legal Hero card type.
-- Random Mode fallback warning remains hidden when no theme filters are provided, keeping Surprise Me runs noise-free.
-- Hover previews regained the double-faced card flip button with state synced to the main tile, highlight only the themes that triggered inclusion, and present a mobile-friendly tap layout with centered positioning plus a close control.
-- Deck summary text view exposes inline flip toggles for double-faced cards so counts and face switching stay in sync.
-- Finished deck summaries now reuse sanitized metadata (with a fallback to deck meta) to display overlap chips that mirror the builder view, and hover overlap pills feature larger, higher-contrast styling for readability.
-- Builder Step 5 commander preview now leverages the in-app hover panel (dropping the external Scryfall link) and the hover reasons list expands naturally without a cramped scrollbar.
-- Finished deck commander preview now mirrors the builder hover chips, showing deck-selected theme overlaps alongside the full commander theme list while keeping thumbnail taps inside the app instead of bouncing to Scryfall.
-- Delivered multi-theme random builds with deterministic cascade, strict match support, and polished HTMX/UI flows.
-- Added opt-in telemetry counters, reroll throttling safeguards, and structured diagnostics exports.
-- Expanded tooling, documentation, and QA coverage for theme governance, performance profiling, and seed history management.
-- Hardened the headless runner against owned-card prompt loops with optional automation overrides and regression coverage.
-- Headless runner random mode now mirrors the web UI configuration surface with CLI flag documentation, dry-run summaries, and JSON export parity.
+- Theme catalog pagination buttons now re-run HTMX processing after fragment fetches so “Next” works reliably in the picker and simple catalog views.
+- Docker entrypoint seeds default theme catalog configuration files into volume-backed deployments, keeping Docker Hub images ready out of the box.
 
-## Highlights
-### Multi-theme random builds
-- Primary/Secondary/Tertiary inputs with deterministic fallback cascade (P+S+T → P+S → P+T → P → synergy overlap → full pool).
-- Strict match toggle persists across UI, API, permalink, and export flows with restored reroll parity and diagnostics integration.
-- Auto-fill helpers for secondary/tertiary slots, a quick “Clear themes” control, and consistent multi-theme metadata across sessions, permalinks, exports, and metrics.
-
-### Telemetry & throttling
-- Opt-in `RANDOM_TELEMETRY` counters capturing usage, fallback reasons, and seed history with NDJSON export endpoint.
-- Reroll throttle enforcement with banner/countdown messaging plus override hooks for attempts and timeout controls.
-- Expanded fast tests validating telemetry counters, throttle behavior, and reroll permutations.
-
-### UI polish
-- Owned Cards library grid uses 160px thumbnails, wider columns, and defers virtualization until large collections to ensure smooth scrolling.
-- Hover card popovers hide the role badge when a card has no role metadata, preventing blank pills in owned library previews.
-- Hover card previews now include a flip control for double-faced cards, stay synchronized with the tile button, highlight the active inclusion themes, and present a centered, readable mobile layout when tapped.
-- Finished deck exports render the same overlap chips as the live builder, backed by metadata fallback logic, and the hover overlap pills are larger with improved contrast.
-- Finished deck commander popovers reuse deck metadata to display overlap chips and commander theme lists, and the commander thumbnail no longer opens Scryfall so tap-to-preview is consistent on mobile.
-- Builder stage card tiles now keep the card art tap/click dedicated to previewing while the lock state is controlled solely by the 🔒 button, preventing accidental locks on touch devices.
-- Builder hover previews now use normalized theme labels (e.g., “Card Advantage”), suppress internal prefixes so build-mode pills match the finished deck summary, and the Step 5 commander preview stays in-app with hover reasons expanding without scrollbars.
-- Deck summary text rows gained inline flip buttons beside card counts to mirror thumbnail behavior for double-faced cards.
-- Random Mode fallback banner is suppressed when all theme inputs are empty so Surprise Me runs stay uncluttered.
-
-### Tooling & docs
-- Random theme exclusion catalog with reporting script and documentation, alongside a multi-theme performance profiler and regression guard.
-- Taxonomy snapshot tooling, splash penalty analytics, and governance documentation updated for strict alias and example enforcement.
-- README, CHANGELOG, and release notes refreshed to cover the random modes feature set.
-- Headless runner documentation now covers random mode CLI flags, env precedence, and parity with the web builder.
-
-### Observability & QA
-- Diagnostics badge polish, recent/favorite seeds panel, seed history API, and structured logging for random builds.
-- Sidecar exports include multi-theme metadata and locked commander indicators with consistent artifact sets.
-- Manual QA checklist updates and broader pytest coverage for multi-theme flows, reroll behavior, performance, and telemetry.
-- Headless runner now auto-resolves owned-card prompts in headless mode with env-overridable defaults and a regression test.
-
-### Maintenance & CI
-- Theme catalog schema now accepts optional IDs and the preview performance warm baseline was regenerated to restore the regression gate.
-- GitHub Actions now includes `httpx` in the default dependency install and executes pytest via `python -m` so FastAPI TestClient suites run without import errors.
-- Fast path validator treats empty synergy arrays as acceptable and only warns on missing or malformed data, reducing noise during automated catalog generation.
-- Tracked the tiny `csv_files/testdata` dataset in Git to guarantee fast determinism tests run against a consistent fixture set.
-- File setup retains cards tagged with the Hero creature type while continuing to skip the non-Commander-legal Hero card type.
-
-## Detailed changes
-### Added
-- **Validation & telemetry tests**
-	- `test_random_reroll_throttle.py` guarding reroll throttle rules.
-	- `test_random_metrics_and_seed_history.py` verifying opt-in telemetry counters and seed history API output.
-	- `test_random_multi_theme_webflows.py` covering reroll-same-commander caching and permalink round-trips for multi-theme runs.
-	- `test_random_multi_theme_filtering.py` ensuring deterministic cascade across success tiers and sidecar metadata.
-	- `test_random_surprise_reroll_behavior.py` protecting Surprise Me input preservation and locked-commander cache reuse.
-	- `test_headless_skips_owned_prompt_when_files_present.py` ensuring headless builds stay non-interactive when owned card lists are present.
-- **Random mode tooling & docs**
-	- Curated theme pool exclusions at `config/random_theme_exclusions.yml`, reporting helper `code/scripts/report_random_theme_pool.py --write-exclusions`, and companion docs in `docs/random_theme_exclusions.md`.
-	- Performance guard `code/scripts/check_random_theme_perf.py` comparing profiler output (`code/scripts/profile_multi_theme_filter.py`) with `config/random_theme_perf_baseline.json` (`--update-baseline` refreshes the file).
-	- Sidecar metadata now records primary/secondary/tertiary themes, resolved combos, fallback reason, and locked commander flag across summary payloads, permalinks, and exports.
-- **UI & diagnostics enhancements**
-	- Auto-fill helpers for secondary and tertiary slots plus a single-click “Clear themes” control.
-	- Diagnostics endpoint `/status/random_theme_stats` surfacing commander/theme token coverage, attempts, timeout flags, and retries exhausted indicators.
-	- Diagnostics badges polished with icons/labels alongside a recent/favorite seeds panel and strict match toggle persistence.
-- **Telemetry & throttling**
-	- Opt-in `RANDOM_TELEMETRY` usage counters, reroll fallback reasons, NDJSON export endpoint, and reroll throttle banner/countdown enforcement.
-- **Governance & taxonomy tooling**
-	- Random theme exclusion catalog sidecars, taxonomy snapshot CLI (`code/scripts/snapshot_taxonomy.py`), splash penalty analytics, and governance docs covering strict alias enforcement and example minimums.
-	- Theme whitelist governance at `config/themes/theme_whitelist.yml`, curated+inferred synergy expansion, and tests such as `test_theme_whitelist_and_synergy_cap.py`.
-	- Editorial scripts for normalization, example padding, governance lint, and catalog merge pipeline (`code/scripts/build_theme_catalog.py`).
-- **Dependencies & infrastructure**
-	- PyYAML optional dependency for governance parsing.
-
-### Changed
-- Multi-theme filtering now pre-computes lowercase token indices and reuses cached columns, reducing pandas `.apply` overhead (profiling mean ~9.3 ms / p95 ~21 ms at seed 42).
-- Strict theme match toggle and auto-fill state persist across HTMX rerolls, API responses, full builds, sessions, permalinks, and exports.
-- Random full builds enforce `RANDOM_BUILD_SUPPRESS_INITIAL_EXPORT=1` by default, eliminating duplicate suffixed decklists.
-- Preview assembly pins curated `example_cards` and `synergy_example_cards` before heuristic sampling with diversity quotas; hover UI consolidated to one panel with resized thumbnails (110→165→230px) and keyboard-accessible DFC flip.
-- List/API filtering path migrated to optimized fast filter (`filter_slugs_fast`) avoiding repeated concatenation and case folding per request.
-- Splash analytics count both static and adaptive penalty reasons and share prefixes for continuity with existing dashboards.
-- Cache bust hooks now clear filter/preview caches on catalog refresh or tagging completion; metrics expose `preview_last_bust_at` and warm cache stats.
-- Theme normalization standardizes terms (ETB → Enter the Battlefield, Pillow Fort → Pillowfort, etc.), with synergy output capped at five entries (curated > enforced > inferred ordering).
-- README, CHANGELOG, and governance docs updated to reflect new workflows, taxonomy snapshots, and telemetry controls.
-- Headless runner random mode uses shared configuration resolution, emits summary/payload artifacts, and exposes CLI flags matching the web UI.
-- Theme catalog schema now allows optional `id` fields on entries so regenerated catalogs validate cleanly.
-
-### Deprecated
-- Price/legality snippet integration remains deferred to the future Budget Mode rollout (`logs/roadmaps/roadmap_9_budget_mode.md`).
-- Legacy client-side mana and color identity parsers are deprecated in favor of server-authoritative fields included in preview/export payloads.
-
-### Fixed
-- Resolved duplicate template environment instantiation that caused inconsistent navigation globals in picker fragments.
-- Ensured preview cache keys include catalog ETag to avoid stale samples after catalog reloads.
-- Suppressed legacy double-export path to prevent creation of `*_1.csv` / `*_1.txt` artifacts.
-- Removed ultra-rare themes (frequency ≤1) unless protected via whitelist, keeping results focused on supported experiences.
-- Corrected commander eligibility rules to restrict non-creature legendary permanents and honor “can be your commander” text.
-- Refreshed `logs/perf/theme_preview_warm_baseline.json` to fix preview performance CI failures stemming from malformed baseline data.
-- Prevented the headless runner from looping on bracket selection when owned card files exist by scripting prompt responses and exposing `HEADLESS_USE_OWNED_ONLY` / `HEADLESS_OWNED_SELECTION` overrides.
-- Fixed file setup filtering so Hero creature type cards remain available even though the Hero card type stays disallowed for Commander.
-
-## Upgrade notes
-- Enable multi-theme random builds via existing Random Mode flags; strict matching persists automatically across UI, API, permalink, and export contexts.
-- Opt into telemetry by setting `RANDOM_TELEMETRY=1`; reroll throttle defaults are active but can be tuned through environment overrides.
-- Run headless random builds with `HEADLESS_RANDOM_MODE=1` or the new CLI `--random-*` flags to mirror Surprise Me behavior, optionally persisting outputs via `--random-output-json`.
-- Refresh performance baselines with `code/scripts/check_random_theme_perf.py --update-baseline` when catalog changes materially affect timings.
-
-## Testing
-```pwsh
-pytest -q code/tests/test_random_reroll_throttle.py code/tests/test_random_metrics_and_seed_history.py
-pytest -q code/tests/test_random_determinism.py code/tests/test_random_build_api.py code/tests/test_seeded_builder_minimal.py code/tests/test_builder_rng_seeded_stream.py
-```
+## Fixed
+- Theme catalog Next pagination button now reprocesses HTMX fragments after manual fetches, restoring navigation controls in theme picker and simple catalog modes.
+- Docker entrypoint seeds default `config/themes` YAML files (synergy pairs, clusters, whitelist, etc.) into mounted volumes so Docker Hub deployments have the expected baseline data.

code/web/templates/themes/catalog_simple.html

@@ -84,7 +84,14 @@
     resultsHost.setAttribute('aria-busy','true');
     fetch('/themes/fragment/list_simple?'+ps, {cache:'no-store'})
       .then(r=>r.text())
-      .then(html=>{ resultsHost.innerHTML=html; resultsHost.removeAttribute('aria-busy'); renderActive(); })
+      .then(html=>{
+        resultsHost.innerHTML=html;
+        if(window.htmx && typeof window.htmx.process==='function'){
+          window.htmx.process(resultsHost);
+        }
+        resultsHost.removeAttribute('aria-busy');
+        renderActive();
+      })
       .catch(()=>{ resultsHost.innerHTML='<div class="empty" style="font-size:13px;">Failed to load.</div>'; resultsHost.removeAttribute('aria-busy'); });
   }
   function performSearch(q){

code/web/templates/themes/picker.html

@@ -163,7 +163,17 @@ mark { background:#fde68a; color:inherit; padding:0 2px; border-radius:2px; }
     toggleRefreshBtn(true);
     fetch('/themes/fragment/list?'+base, {cache:'no-store', signal: controller.signal})
       .then(r=>r.text())
-      .then(html=>{ if(controller.signal.aborted) return; target.innerHTML = html; target.removeAttribute('aria-busy'); target.classList.remove('preload-hide'); listRenderComplete(); toggleRefreshBtn(false); })
+      .then(html=>{
+        if(controller.signal.aborted) return;
+        target.innerHTML = html;
+        if(window.htmx && typeof window.htmx.process==='function'){
+          window.htmx.process(target);
+        }
+        target.removeAttribute('aria-busy');
+        target.classList.remove('preload-hide');
+        listRenderComplete();
+        toggleRefreshBtn(false);
+      })
       .catch(err=>{ if(controller.signal.aborted) return; target.innerHTML = '<div class="error" role="alert">Failed loading themes. <button id="retry-fetch" class="btn btn-ghost">Retry</button></div>'; target.removeAttribute('aria-busy'); target.classList.remove('preload-hide'); attachRetry(); structuredLog('list_fetch_error'); announceResultCount(); toggleRefreshBtn(false); });
   }
   function attachRetry(){ var b=document.getElementById('retry-fetch'); if(!b) return; b.addEventListener('click', function(){ fetchList(); }); }

config/themes/theme_popularity_metrics.json

@@ -1,11 +0,0 @@
-{
-  "generated_at": "2025-09-18T11:59:36",
-  "bucket_counts": {
-    "Very Common": 61,
-    "Rare": 485,
-    "Common": 38,
-    "Niche": 100,
-    "Uncommon": 49
-  },
-  "total_themes": 733
-}

docker-compose.yml

@@ -92,7 +92,7 @@ services:
       # WEB_THEME_FILTER_PREWARM: "0"
       WEB_AUTO_ENFORCE: "0"         # 1=auto-run compliance export after builds
       WEB_CUSTOM_EXPORT_BASE: ""    # Optional: custom base dir for deck export artifacts
-      APP_VERSION: "2.3.1"          # Displayed version label (set per release/tag)
+      APP_VERSION: "2.3.2"          # Displayed version label (set per release/tag)
 
       # ------------------------------------------------------------------
       # Misc / Land Selection (Step 7) Environment Tuning

dockerhub-docker-compose.yml

@@ -73,7 +73,7 @@ services:
       # WEB_THEME_FILTER_PREWARM: "0"
       WEB_AUTO_ENFORCE: "0"         # 1=auto compliance JSON export after builds
       WEB_CUSTOM_EXPORT_BASE: ""     # Optional export base override
-      APP_VERSION: "v2.3.1"        # Displayed in footer/health
+      APP_VERSION: "v2.3.2"        # Displayed in footer/health
 
       # ------------------------------------------------------------------
       # Misc Land Selection Tuning (Step 7)

docs/releases/v2.3.2.md

@@ -0,0 +1,9 @@
+# MTG Python Deckbuilder v2.3.2
+
+## Summary
+- Theme catalog pagination buttons now re-run HTMX processing after fragment fetches so “Next” works reliably in the picker and simple catalog views.
+- Docker entrypoint seeds default theme catalog configuration files into volume-backed deployments, keeping Docker Hub images ready out of the box.
+
+## Fixed
+- Theme catalog Next pagination button now reprocesses HTMX fragments after manual fetches, restoring navigation controls in theme picker and simple catalog modes.
+- Docker entrypoint seeds default `config/themes` YAML files (synergy pairs, clusters, whitelist, etc.) into mounted volumes so Docker Hub deployments have the expected baseline data.

entrypoint.sh

@@ -4,7 +4,7 @@ set -e
 # Seed default config files into /app/config if missing (handles first-run with mounted volume)
 seed_defaults() {
     # Ensure base config directory exists
-    mkdir -p /app/config /app/config/card_lists
+    mkdir -p /app/config /app/config/card_lists /app/config/themes
 
     # Copy from baked-in defaults if targets are missing
     if [ -d "/.defaults/config" ]; then
@@ -20,6 +20,21 @@ seed_defaults() {
                 [ -f "/app/config/card_lists/$base" ] || cp "$f" "/app/config/card_lists/$base" 2>/dev/null || true
             done
         fi
+        # Seed theme catalog defaults (e.g., synergy pairs, clusters, whitelist)
+        if [ -d "/.defaults/config/themes" ]; then
+            for f in /.defaults/config/themes/*; do
+                [ -e "$f" ] || continue
+                base=$(basename "$f")
+                dest="/app/config/themes/$base"
+                if [ -d "$f" ]; then
+                    if [ ! -d "$dest" ]; then
+                        cp -r "$f" "$dest" 2>/dev/null || true
+                    fi
+                else
+                    [ -f "$dest" ] || cp "$f" "$dest" 2>/dev/null || true
+                fi
+            done
+        fi
     fi
 }
 

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mtg-deckbuilder"
-version = "2.3.1"
+version = "2.3.2"
 description = "A command-line tool for building and analyzing Magic: The Gathering decks"
 readme = "README.md"
 license = {file = "LICENSE"}