| {{ color|title }} |
{{ payload.group_count or 0 }} |
{{ payload.faces_dropped or 0 }} |
{{ payload.multi_face_rows or 0 }} |
- {% set entries = payload.entries or [] %}
+ {% set entries = (payload.entries | default([])) %}
{% if entries %}
{{ entries|length }} recorded
+ {% set preview = entries[:5] %}
- {% for entry in entries %}
- {% if loop.index0 < 5 %}
- -
- {{ entry.name }} — {{ entry.total_faces }} faces (dropped {{ entry.dropped_faces }})
-
- {% elif loop.index0 == 5 %}
- - … {{ entries|length - 5 }} more entries
- {% break %}
- {% endif %}
+ {% for entry in preview %}
+ -
+ {{ entry.name }} — {{ entry.total_faces }} faces (dropped {{ entry.dropped_faces }})
+
{% endfor %}
+ {% if entries|length > preview|length %}
+ - … {{ entries|length - preview|length }} more entries
+ {% endif %}
{% else %}
@@ -134,6 +137,125 @@
try { fetch('/status/sys', { cache: 'no-store' }).then(function(r){ return r.json(); }).then(render).catch(function(){ el.textContent='Unavailable'; }); } catch(_){ el.textContent='Unavailable'; }
}
load();
+ // Environment flags card
+ (function(){
+ var target = document.getElementById('envFlags');
+ if (!target) return;
+ function renderEnv(data){
+ if (!data || !data.flags) { target.textContent = 'Flags unavailable'; return; }
+ var f = data.flags;
+ function as01(v){ return (v ? '1' : '0'); }
+ var lines = [];
+ lines.push('Homepage & UI: '
+ + 'SHOW_SETUP=' + as01(f.SHOW_SETUP)
+ + ', SHOW_LOGS=' + as01(f.SHOW_LOGS)
+ + ', SHOW_DIAGNOSTICS=' + as01(f.SHOW_DIAGNOSTICS)
+ + ', SHOW_COMMANDERS=' + as01(f.SHOW_COMMANDERS)
+ + ', ENABLE_THEMES=' + as01(f.ENABLE_THEMES)
+ + ', ENABLE_CUSTOM_THEMES=' + as01(f.ENABLE_CUSTOM_THEMES)
+ + ', ALLOW_MUST_HAVES=' + as01(f.ALLOW_MUST_HAVES)
+ + ', THEME=' + String(f.DEFAULT_THEME || '')
+ + ', THEME_MATCH_MODE=' + String(f.THEME_MATCH_MODE || '')
+ + ', USER_THEME_LIMIT=' + String(f.USER_THEME_LIMIT || '')
+ + ' ');
+ lines.push('Random: '
+ + 'RANDOM_MODES=' + as01(f.RANDOM_MODES)
+ + ', RANDOM_UI=' + as01(f.RANDOM_UI)
+ + ', RANDOM_MAX_ATTEMPTS=' + String(f.RANDOM_MAX_ATTEMPTS || '')
+ + ', RANDOM_TIMEOUT_MS=' + String(f.RANDOM_TIMEOUT_MS || '')
+ + ', RANDOM_REROLL_THROTTLE_MS=' + String(f.RANDOM_REROLL_THROTTLE_MS || '')
+ + ', RANDOM_TELEMETRY=' + as01(f.RANDOM_TELEMETRY)
+ + ', RANDOM_STRUCTURED_LOGS=' + as01(f.RANDOM_STRUCTURED_LOGS)
+ + ' ');
+ lines.push('Rate limiting (random): '
+ + 'RATE_LIMIT_ENABLED=' + as01(f.RATE_LIMIT_ENABLED)
+ + ', WINDOW_S=' + String(f.RATE_LIMIT_WINDOW_S || '')
+ + ', RANDOM=' + String(f.RANDOM_RATE_LIMIT_RANDOM || '')
+ + ', BUILD=' + String(f.RANDOM_RATE_LIMIT_BUILD || '')
+ + ', SUGGEST=' + String(f.RANDOM_RATE_LIMIT_SUGGEST || '')
+ + ' ');
+ target.innerHTML = lines.join('');
+ }
+ try { fetch('/status/sys', { cache: 'no-store' }).then(function(r){ return r.json(); }).then(renderEnv).catch(function(){ target.textContent='Flags unavailable'; }); } catch(_){ target.textContent='Flags unavailable'; }
+ })();
+ var themeSuppEl = document.getElementById('themeSuppMetrics');
+ function renderThemeSupp(payload){
+ if (!themeSuppEl) return;
+ try {
+ if (!payload || payload.ok !== true) {
+ themeSuppEl.textContent = 'Theme metrics unavailable';
+ return;
+ }
+ var metrics = payload.metrics || {};
+ var total = metrics.total_builds != null ? Number(metrics.total_builds) : 0;
+ if (!total) {
+ themeSuppEl.textContent = 'No deck builds recorded yet.';
+ return;
+ }
+ var withUser = metrics.with_user_themes != null ? Number(metrics.with_user_themes) : 0;
+ var share = metrics.user_theme_share != null ? Number(metrics.user_theme_share) : 0;
+ var sharePct = !Number.isNaN(share) ? (share * 100).toFixed(1) + '%' : '0%';
+ var summary = metrics.last_summary || {};
+ var commander = Array.isArray(summary.commanderThemes) ? summary.commanderThemes : [];
+ var user = Array.isArray(summary.userThemes) ? summary.userThemes : [];
+ var merged = Array.isArray(summary.mergedThemes) ? summary.mergedThemes : [];
+ var unresolvedCount = summary.unresolvedCount != null ? Number(summary.unresolvedCount) : 0;
+ var unresolved = Array.isArray(summary.unresolved) ? summary.unresolved : [];
+ var mode = summary.mode || 'AND';
+ var weight = summary.weight != null ? Number(summary.weight) : 1;
+ var updated = metrics.last_updated || '';
+ var topUser = Array.isArray(metrics.top_user_themes) ? metrics.top_user_themes : [];
+ function joinList(arr){
+ if (!arr || !arr.length) return '—';
+ return arr.join(', ');
+ }
+ var html = '';
+ html += 'Total builds: ' + String(total) + ' (user themes ' + String(withUser) + '\u00a0| ' + sharePct + ') ';
+ if (updated) {
+ html += 'Last updated: ' + String(updated) + ' ';
+ }
+ html += 'Commander themes: ' + joinList(commander) + ' ';
+ html += 'User themes: ' + joinList(user) + ' ';
+ html += 'Merged: ' + joinList(merged) + ' ';
+ var unresolvedLabel = '0';
+ if (unresolvedCount > 0) {
+ unresolvedLabel = String(unresolvedCount) + ' (' + joinList(unresolved) + ')';
+ } else {
+ unresolvedLabel = '0';
+ }
+ html += 'Unresolved: ' + unresolvedLabel + ' ';
+ html += 'Mode ' + String(mode) + ' · Weight ' + weight.toFixed(2) + ' ';
+ if (topUser.length) {
+ var topLine = topUser.slice(0, 5).map(function(item){
+ if (!item) return '';
+ var t = item.theme != null ? String(item.theme) : '';
+ var c = item.count != null ? String(item.count) : '0';
+ return t + ' (' + c + ')';
+ }).filter(Boolean);
+ if (topLine.length) {
+ html += 'Top user themes: ' + topLine.join(', ') + ' ';
+ }
+ }
+ themeSuppEl.innerHTML = html;
+ } catch (_){
+ themeSuppEl.textContent = 'Theme metrics unavailable';
+ }
+ }
+ function loadThemeSupp(){
+ if (!themeSuppEl) return;
+ themeSuppEl.textContent = 'Loading theme metrics…';
+ fetch('/status/theme_metrics', { cache: 'no-store' })
+ .then(function(resp){
+ if (resp.status === 404) {
+ themeSuppEl.textContent = 'Diagnostics disabled (metrics unavailable)';
+ return null;
+ }
+ return resp.json();
+ })
+ .then(function(data){ if (data) renderThemeSupp(data); })
+ .catch(function(){ themeSuppEl.textContent = 'Theme metrics unavailable'; });
+ }
+ loadThemeSupp();
var tokenEl = document.getElementById('themeTokenStats');
function renderTokens(payload){
if (!tokenEl) return;
diff --git a/config/deck.json b/config/deck.json
index ca89c88..4e89825 100644
--- a/config/deck.json
+++ b/config/deck.json
@@ -23,5 +23,9 @@
"exclude_cards": ["Chaos Orb"],
"enforcement_mode": "warn",
"allow_illegal": false,
- "fuzzy_matching": true
+ "fuzzy_matching": true,
+ "additional_themes": [],
+ "theme_match_mode": "permissive",
+ "userThemes": [],
+ "themeCatalogVersion": null
}
\ No newline at end of file
diff --git a/docker-compose.yml b/docker-compose.yml
index e40ef32..b221204 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -18,9 +18,12 @@ services:
SHOW_LOGS: "1" # 1=enable /logs page; 0=hide
SHOW_SETUP: "1" # 1=show Setup/Tagging card; 0=hide (still runs if WEB_AUTO_SETUP=1)
SHOW_DIAGNOSTICS: "1" # 1=enable /diagnostics & /diagnostics/perf; 0=hide
+ SHOW_COMMANDERS: "1" # 1=show Commanders browser/pages
ENABLE_PWA: "0" # 1=serve manifest/service worker (experimental)
ENABLE_THEMES: "1" # 1=expose theme selector; 0=hide (THEME still applied)
ENABLE_PRESETS: "0" # 1=show presets section
+ ENABLE_CUSTOM_THEMES: "1" # 1=expose Additional Themes panel for user-supplied tags
+ USER_THEME_LIMIT: "8" # Maximum number of user-supplied supplemental themes stored in session
WEB_VIRTUALIZE: "1" # 1=enable list virtualization in Step 5
ALLOW_MUST_HAVES: "1" # 1=enable must-include/must-exclude cards feature; 0=disable
SHOW_MISC_POOL: "0"
@@ -47,6 +50,9 @@ services:
# RANDOM_UI: "1" # 1=show Surprise/Theme/Reroll/Share controls in UI
RANDOM_MAX_ATTEMPTS: "5" # cap retry attempts
RANDOM_TIMEOUT_MS: "5000" # per-build timeout in ms
+ RANDOM_REROLL_THROTTLE_MS: "350" # minimum ms between reroll requests (client guard)
+ RANDOM_STRUCTURED_LOGS: "0" # 1=emit structured JSON logs for random builds
+ RANDOM_TELEMETRY: "0" # 1=emit lightweight timing/attempt metrics (dev/diagnostics)
RANDOM_THEME: "" # optional legacy theme alias (maps to primary theme)
RANDOM_PRIMARY_THEME: "" # optional primary theme slug override
RANDOM_SECONDARY_THEME: "" # optional secondary theme slug override
@@ -61,8 +67,16 @@ services:
RANDOM_OUTPUT_JSON: "" # path or directory for random build output payload
# RANDOM_BUILD_SUPPRESS_INITIAL_EXPORT: "1" # (now defaults to 1 automatically for random builds; set to 0 to force legacy double-export behavior)
+ # Random rate limiting (optional; protects from abuse or accidental hammers)
+ RATE_LIMIT_ENABLED: "0" # 1=enable server-side rate limiting for random endpoints
+ RATE_LIMIT_WINDOW_S: "10" # window size in seconds
+ RATE_LIMIT_RANDOM: "10" # max random attempts per window
+ RATE_LIMIT_BUILD: "10" # max builds per window
+ RATE_LIMIT_SUGGEST: "30" # max suggestions per window
+
# Theming
THEME: "dark" # system|light|dark
+ THEME_MATCH_MODE: "permissive" # permissive|strict fuzzy match mode for supplemental themes
# ------------------------------------------------------------------
# Setup / Tagging / Catalog Controls
@@ -121,6 +135,8 @@ services:
# CSV_FILES_DIR: "/app/csv_files"
# Inject a one-off synthetic CSV for index testing without altering shards
# CARD_INDEX_EXTRA_CSV: ""
+ # DECK_ADDITIONAL_THEMES: ""
+ # THEME_MATCH_MODE: "permissive"
# ------------------------------------------------------------------
# Headless / Non-interactive Build Configuration
diff --git a/dockerhub-docker-compose.yml b/dockerhub-docker-compose.yml
index 15f49a1..2477f28 100644
--- a/dockerhub-docker-compose.yml
+++ b/dockerhub-docker-compose.yml
@@ -20,8 +20,11 @@ services:
SHOW_LOGS: "1" # 1=enable /logs page; 0=hide
SHOW_SETUP: "1" # 1=show Setup/Tagging card; 0=hide (still runs if WEB_AUTO_SETUP=1)
SHOW_DIAGNOSTICS: "1" # 1=enable /diagnostics & /diagnostics/perf; 0=hide
+ SHOW_COMMANDERS: "1" # 1=show Commanders browser/pages
ENABLE_PWA: "0" # 1=serve manifest/service worker (experimental)
ENABLE_THEMES: "1" # 1=expose theme selector; 0=hide (THEME still applied)
+ ENABLE_CUSTOM_THEMES: "1" # 1=expose Additional Themes panel for user-supplied tags
+ USER_THEME_LIMIT: "8" # Maximum number of user-supplied supplemental themes stored in session
ENABLE_PRESETS: "0" # 1=show presets section
WEB_VIRTUALIZE: "1" # 1=enable list virtualization in Step 5
ALLOW_MUST_HAVES: "1" # 1=enable must-include/must-exclude cards feature; 0=disable
@@ -49,6 +52,9 @@ services:
RANDOM_UI: "1" # 1=show Surprise/Theme/Reroll/Share controls in UI
RANDOM_MAX_ATTEMPTS: "5" # cap retry attempts
RANDOM_TIMEOUT_MS: "5000" # per-build timeout in ms
+ RANDOM_REROLL_THROTTLE_MS: "350" # minimum ms between reroll requests (client guard)
+ RANDOM_STRUCTURED_LOGS: "0" # 1=emit structured JSON logs for random builds
+ RANDOM_TELEMETRY: "0" # 1=emit lightweight timing/attempt metrics (dev/diagnostics)
RANDOM_THEME: "" # optional legacy theme alias (maps to primary theme)
RANDOM_PRIMARY_THEME: "" # optional primary theme slug override
RANDOM_SECONDARY_THEME: "" # optional secondary theme slug override
@@ -63,8 +69,16 @@ services:
RANDOM_OUTPUT_JSON: "" # path or directory for random build output payload
# RANDOM_BUILD_SUPPRESS_INITIAL_EXPORT: "1" # (now defaults to 1 automatically for random builds; set to 0 to force legacy double-export behavior)
+ # Random rate limiting (optional; protects from abuse or accidental hammers)
+ RATE_LIMIT_ENABLED: "0" # 1=enable server-side rate limiting for random endpoints
+ RATE_LIMIT_WINDOW_S: "10" # window size in seconds
+ RATE_LIMIT_RANDOM: "10" # max random attempts per window
+ RATE_LIMIT_BUILD: "10" # max builds per window
+ RATE_LIMIT_SUGGEST: "30" # max suggestions per window
+
# Theming
THEME: "dark" # system|light|dark
+ THEME_MATCH_MODE: "permissive" # permissive|strict fuzzy match mode for supplemental themes
# ------------------------------------------------------------------
# Setup / Tagging / Catalog Controls
@@ -123,6 +137,8 @@ services:
# CSV_FILES_DIR: "/app/csv_files"
# Inject a one-off synthetic CSV for index testing without altering shards
# CARD_INDEX_EXTRA_CSV: ""
+ # DECK_ADDITIONAL_THEMES: ""
+ # THEME_MATCH_MODE: "permissive"
# ------------------------------------------------------------------
# Headless / Non-interactive Build Configuration
diff --git a/docs/theme_catalog_advanced.md b/docs/theme_catalog_advanced.md
index 2d74cee..be6bb14 100644
--- a/docs/theme_catalog_advanced.md
+++ b/docs/theme_catalog_advanced.md
@@ -3,6 +3,7 @@
Additional details for developers and power users working with the theme catalog, editorial tooling, and diagnostics.
## Table of contents
+- [theme_catalog.csv schema](#theme_catalogcsv-schema)
- [HTMX API endpoints](#htmx-api-endpoints)
- [Caching, diagnostics, and metrics](#caching-diagnostics-and-metrics)
- [Governance principles](#governance-principles)
@@ -18,7 +19,20 @@ Additional details for developers and power users working with the theme catalog
- [Description mapping overrides](#description-mapping-overrides)
- [Validation and schema tooling](#validation-and-schema-tooling)
----
+
+## theme_catalog.csv schema
+`theme_catalog.csv` is the normalized artifact consumed by headless builds, supplemental themes, and diagnostics panels. The file starts with a header comment in the format `# theme_catalog version=` followed by a standard CSV header with these columns:
+
+| Column | Description |
+| --- | --- |
+| `theme` | Normalized display label used across the app and JSON exports. |
+| `commander_count` | Number of commanders tagged with the theme in `commander_cards.csv`. |
+| `card_count` | Number of non-commander cards carrying the theme tag across primary CSVs. |
+| `source_count` | Combined count (`commander_count + card_count`) to simplify weighting heuristics. |
+| `last_generated_at` | ISO-8601 timestamp captured at generation time (UTC). Useful for verifying stale catalogs in diagnostics. |
+| `version` | Deterministic SHA-256 prefix derived from the ordered theme list; this value flows into exports as `themeCatalogVersion` and `/status/theme_metrics`. |
+
+Consumers should treat additional columns as experimental. If you add new fields, update this table and the supplemental theme tests that assert schema coverage.
## HTMX API endpoints
The upcoming theme picker UI is powered by two FastAPI endpoints.
diff --git a/docs/web_ui_deep_dive.md b/docs/web_ui_deep_dive.md
index 051b4f3..54e6b69 100644
--- a/docs/web_ui_deep_dive.md
+++ b/docs/web_ui_deep_dive.md
@@ -99,5 +99,6 @@ Open the Owned tile to manage uploaded inventories:
## Diagnostics and logs
- `SHOW_DIAGNOSTICS=1` unlocks the `/diagnostics` page with system summaries (`/status/sys`), feature flags, and per-request `X-Request-ID` headers.
+- Supplemental theme telemetry lives at `/status/theme_metrics` (enabled with `ENABLE_CUSTOM_THEMES=1`); the diagnostics page renders commander themes, user-supplied themes, merged totals, and unresolved counts using the `userThemes`/`themeCatalogVersion` metadata exported from builds.
- `SHOW_LOGS=1` turns on the `/logs` viewer with level & keyword filters, auto-refresh, and copy-to-clipboard.
- Health probes live at `/healthz` and return `{status, version, uptime_seconds}` for integration with uptime monitors.
|