From 1bcd4819da65ed012f7de660934105f24a0de7c0 Mon Sep 17 00:00:00 2001
From: Matthew Spah <spahmatthew@gmail.com>
Date: Fri, 25 Sep 2026 08:18:29 -0700
Subject: [PATCH 1/2] refactor: clarify team presentation ownership

---
 app/web/templates/_summary_cards.html              |  9 +++++++++
 ...selector_form.html => _team_selector_form.html} |  6 +++---
 app/web/templates/baserunners.html                 | 12 ++----------
 app/web/templates/comparison.html                  | 14 ++++----------
 app/web/templates/hits_allowed.html                | 12 ++----------
 app/web/templates/index.html                       | 12 ++----------
 app/web/templates/pitching.html                    | 12 ++----------
 app/web/templates/run_differential.html            | 12 ++----------
 app/web/templates/runs.html                        | 12 ++----------
 app/web/templates/strikeouts.html                  | 12 ++----------
 docs/ui-information-architecture.md                |  6 ++++++
 tests/test_web.py                                  |  2 ++
 tests/test_web_comparison.py                       |  4 ++++
 tests/test_web_page_scaffolding.py                 | 10 ++++++++++
 14 files changed, 52 insertions(+), 83 deletions(-)
 create mode 100644 app/web/templates/_summary_cards.html
 rename app/web/templates/{_selector_form.html => _team_selector_form.html} (90%)

diff --git a/app/web/templates/_summary_cards.html b/app/web/templates/_summary_cards.html
new file mode 100644
index 0000000..036a8c4
--- /dev/null
+++ b/app/web/templates/_summary_cards.html
@@ -0,0 +1,9 @@
+<section class="{{ summary_class | default('summary') }}" aria-label="{{ summary_label | default('Summary statistics') }}">
+  {% for card in summary_cards %}
+    <article class="card summary-card">
+      <p class="summary-card__label">{{ card.label }}</p>
+      <p class="summary-card__value">{{ card.value }}</p>
+      <p class="summary-card__caption">{{ card.caption }}</p>
+    </article>
+  {% endfor %}
+</section>
diff --git a/app/web/templates/_selector_form.html b/app/web/templates/_team_selector_form.html
similarity index 90%
rename from app/web/templates/_selector_form.html
rename to app/web/templates/_team_selector_form.html
index 53abacd..75ce4f2 100644
--- a/app/web/templates/_selector_form.html
+++ b/app/web/templates/_team_selector_form.html
@@ -1,6 +1,6 @@
-{# Shared team/season/window controls. Both metric pages post to their own path
-   via form_action, so one selector serves both without a second selection
-   system. The route validates the team-season pair on every request. #}
+{# Team-only GET controls for team_id, season, and window. Each Team metric
+   supplies form_action; the Team-season catalog supports season-selector.js.
+   Routes validate the Team-season pair even without JavaScript. #}
 <script type="application/json" id="team-seasons-data">{{ team_seasons_catalog | tojson }}</script>
 
 <form class="controls card" method="get" action="{{ form_action }}">
diff --git a/app/web/templates/baserunners.html b/app/web/templates/baserunners.html
index 073ed83..3ae94a6 100644
--- a/app/web/templates/baserunners.html
+++ b/app/web/templates/baserunners.html
@@ -34,7 +34,7 @@ <h2>No team data has been imported yet</h2>
       <pre class="command"><code>{{ import_command }}</code></pre>
     </section>
   {% else %}
-    {% include "_selector_form.html" %}
+    {% include "_team_selector_form.html" %}
 
     {% if state == "not_found" %}
       <section class="card notice">
@@ -72,15 +72,7 @@ <h2>{{ analysis.team_name }} — Baserunners per Game</h2>
         <div class="chart-card__figure">{{ chart_html | safe }}</div>
       </section>
 
-      <section class="summary" aria-label="Summary statistics">
-        {% for card in summary_cards %}
-          <article class="card summary-card">
-            <p class="summary-card__label">{{ card.label }}</p>
-            <p class="summary-card__value">{{ card.value }}</p>
-            <p class="summary-card__caption">{{ card.caption }}</p>
-          </article>
-        {% endfor %}
-      </section>
+      {% include "_summary_cards.html" %}
 
       <section class="about">
         <span class="about__icon" aria-hidden="true">
diff --git a/app/web/templates/comparison.html b/app/web/templates/comparison.html
index 2281fbd..2aef704 100644
--- a/app/web/templates/comparison.html
+++ b/app/web/templates/comparison.html
@@ -33,7 +33,7 @@ <h2>No team data has been imported yet</h2>
       <pre class="command"><code>{{ import_command }}</code></pre>
     </section>
   {% else %}
-    {% include "_selector_form.html" %}
+    {% include "_team_selector_form.html" %}
 
     {% if state == "not_found" %}
       <section class="card notice">
@@ -65,15 +65,9 @@ <h2>{{ analysis.team_name }} — Hits vs Batting Strikeouts</h2>
         </div>
       </section>
 
-      <section class="summary summary--comparison" aria-label="Comparison summary statistics">
-        {% for card in summary_cards %}
-          <article class="card summary-card">
-            <p class="summary-card__label">{{ card.label }}</p>
-            <p class="summary-card__value">{{ card.value }}</p>
-            <p class="summary-card__caption">{{ card.caption }}</p>
-          </article>
-        {% endfor %}
-      </section>
+      {% with summary_class="summary summary--comparison", summary_label="Comparison summary statistics" %}
+        {% include "_summary_cards.html" %}
+      {% endwith %}
 
       <section class="about">
         <span class="about__icon" aria-hidden="true">
diff --git a/app/web/templates/hits_allowed.html b/app/web/templates/hits_allowed.html
index 6b4e438..98245a9 100644
--- a/app/web/templates/hits_allowed.html
+++ b/app/web/templates/hits_allowed.html
@@ -34,7 +34,7 @@ <h2>No team data has been imported yet</h2>
       <pre class="command"><code>{{ import_command }}</code></pre>
     </section>
   {% else %}
-    {% include "_selector_form.html" %}
+    {% include "_team_selector_form.html" %}
 
     {% if state == "not_found" %}
       <section class="card notice">
@@ -72,15 +72,7 @@ <h2>{{ analysis.team_name }} &mdash; Hits Allowed per Game</h2>
         <div class="chart-card__figure">{{ chart_html | safe }}</div>
       </section>
 
-      <section class="summary" aria-label="Summary statistics">
-        {% for card in summary_cards %}
-          <article class="card summary-card">
-            <p class="summary-card__label">{{ card.label }}</p>
-            <p class="summary-card__value">{{ card.value }}</p>
-            <p class="summary-card__caption">{{ card.caption }}</p>
-          </article>
-        {% endfor %}
-      </section>
+      {% include "_summary_cards.html" %}
 
       <section class="about">
         <span class="about__icon" aria-hidden="true">
diff --git a/app/web/templates/index.html b/app/web/templates/index.html
index b48b2be..388594c 100644
--- a/app/web/templates/index.html
+++ b/app/web/templates/index.html
@@ -33,7 +33,7 @@ <h2>No team data has been imported yet</h2>
       <pre class="command"><code>{{ import_command }}</code></pre>
     </section>
   {% else %}
-    {% include "_selector_form.html" %}
+    {% include "_team_selector_form.html" %}
 
     {% if state == "not_found" %}
       <section class="card notice">
@@ -51,15 +51,7 @@ <h2>{{ analysis.team_name }} — Hits per Game</h2>
         <div class="chart-card__figure">{{ chart_html | safe }}</div>
       </section>
 
-      <section class="summary" aria-label="Summary statistics">
-        {% for card in summary_cards %}
-          <article class="card summary-card">
-            <p class="summary-card__label">{{ card.label }}</p>
-            <p class="summary-card__value">{{ card.value }}</p>
-            <p class="summary-card__caption">{{ card.caption }}</p>
-          </article>
-        {% endfor %}
-      </section>
+      {% include "_summary_cards.html" %}
 
       <section class="about">
         <span class="about__icon" aria-hidden="true">
diff --git a/app/web/templates/pitching.html b/app/web/templates/pitching.html
index ac392eb..61346dc 100644
--- a/app/web/templates/pitching.html
+++ b/app/web/templates/pitching.html
@@ -34,7 +34,7 @@ <h2>No team data has been imported yet</h2>
       <pre class="command"><code>{{ import_command }}</code></pre>
     </section>
   {% else %}
-    {% include "_selector_form.html" %}
+    {% include "_team_selector_form.html" %}
 
     {% if state == "not_found" %}
       <section class="card notice">
@@ -71,15 +71,7 @@ <h2>{{ analysis.team_name }} &mdash; Pitches per Game</h2>
         <div class="chart-card__figure">{{ chart_html | safe }}</div>
       </section>
 
-      <section class="summary" aria-label="Summary statistics">
-        {% for card in summary_cards %}
-          <article class="card summary-card">
-            <p class="summary-card__label">{{ card.label }}</p>
-            <p class="summary-card__value">{{ card.value }}</p>
-            <p class="summary-card__caption">{{ card.caption }}</p>
-          </article>
-        {% endfor %}
-      </section>
+      {% include "_summary_cards.html" %}
 
       <section class="about">
         <span class="about__icon" aria-hidden="true">
diff --git a/app/web/templates/run_differential.html b/app/web/templates/run_differential.html
index 8f9b537..f5f99f0 100644
--- a/app/web/templates/run_differential.html
+++ b/app/web/templates/run_differential.html
@@ -34,7 +34,7 @@ <h2>No team data has been imported yet</h2>
       <pre class="command"><code>{{ import_command }}</code></pre>
     </section>
   {% else %}
-    {% include "_selector_form.html" %}
+    {% include "_team_selector_form.html" %}
 
     {% if state == "not_found" %}
       <section class="card notice">
@@ -73,15 +73,7 @@ <h2>{{ analysis.team_name }} — Run Differential per Game</h2>
         <div class="chart-card__figure">{{ chart_html | safe }}</div>
       </section>
 
-      <section class="summary" aria-label="Summary statistics">
-        {% for card in summary_cards %}
-          <article class="card summary-card">
-            <p class="summary-card__label">{{ card.label }}</p>
-            <p class="summary-card__value">{{ card.value }}</p>
-            <p class="summary-card__caption">{{ card.caption }}</p>
-          </article>
-        {% endfor %}
-      </section>
+      {% include "_summary_cards.html" %}
 
       <section class="about">
         <span class="about__icon" aria-hidden="true">
diff --git a/app/web/templates/runs.html b/app/web/templates/runs.html
index 98a006d..6938553 100644
--- a/app/web/templates/runs.html
+++ b/app/web/templates/runs.html
@@ -33,7 +33,7 @@ <h2>No team data has been imported yet</h2>
       <pre class="command"><code>{{ import_command }}</code></pre>
     </section>
   {% else %}
-    {% include "_selector_form.html" %}
+    {% include "_team_selector_form.html" %}
 
     {% if state == "not_found" %}
       <section class="card notice">
@@ -51,15 +51,7 @@ <h2>{{ analysis.team_name }} — Runs Scored per Game</h2>
         <div class="chart-card__figure">{{ chart_html | safe }}</div>
       </section>
 
-      <section class="summary" aria-label="Summary statistics">
-        {% for card in summary_cards %}
-          <article class="card summary-card">
-            <p class="summary-card__label">{{ card.label }}</p>
-            <p class="summary-card__value">{{ card.value }}</p>
-            <p class="summary-card__caption">{{ card.caption }}</p>
-          </article>
-        {% endfor %}
-      </section>
+      {% include "_summary_cards.html" %}
 
       <section class="about">
         <span class="about__icon" aria-hidden="true">
diff --git a/app/web/templates/strikeouts.html b/app/web/templates/strikeouts.html
index 0cbfc9f..8e4547c 100644
--- a/app/web/templates/strikeouts.html
+++ b/app/web/templates/strikeouts.html
@@ -33,7 +33,7 @@ <h2>No team data has been imported yet</h2>
       <pre class="command"><code>{{ import_command }}</code></pre>
     </section>
   {% else %}
-    {% include "_selector_form.html" %}
+    {% include "_team_selector_form.html" %}
 
     {% if state == "not_found" %}
       <section class="card notice">
@@ -70,15 +70,7 @@ <h2>{{ analysis.team_name }} — Batting Strikeouts per Game</h2>
         <div class="chart-card__figure">{{ chart_html | safe }}</div>
       </section>
 
-      <section class="summary" aria-label="Summary statistics">
-        {% for card in summary_cards %}
-          <article class="card summary-card">
-            <p class="summary-card__label">{{ card.label }}</p>
-            <p class="summary-card__value">{{ card.value }}</p>
-            <p class="summary-card__caption">{{ card.caption }}</p>
-          </article>
-        {% endfor %}
-      </section>
+      {% include "_summary_cards.html" %}
 
       <section class="about">
         <span class="about__icon" aria-hidden="true">
diff --git a/docs/ui-information-architecture.md b/docs/ui-information-architecture.md
index 2413b52..6d60f45 100644
--- a/docs/ui-information-architecture.md
+++ b/docs/ui-information-architecture.md
@@ -21,6 +21,12 @@ navigation through `_team_navigation.html`. Individual metric templates retain
 selectors, charts, interpretation, and recovery states. A future Player UI can
 extend the same shell without copying Team assumptions.
 
+Team metric pages include `_team_selector_form.html` for their Team, season, and
+rolling-window GET controls. It relies on the Team-season catalog and stays
+outside the entity-neutral shell; future Player selection should follow its own
+requirements. The small `_summary_cards.html` partial renders route-provided
+cards and preserves Comparison's distinct section class and accessible label.
+
 The brand links to bare `/`. On Team pages, Teams links to the selection-aware
 Hits URL. Metric links preserve `team_id`, `season`, and `window`, including the
 existing requested-versus-resolved distinction in terminal states. Generic
diff --git a/tests/test_web.py b/tests/test_web.py
index f96d34a..d605b2d 100644
--- a/tests/test_web.py
+++ b/tests/test_web.py
@@ -234,6 +234,8 @@ def test_page_contains_the_summary_cards(client: TestClient, seed: SeedFn) -> No
     """Milestone 5 replaced the prior-window card with the MLB comparison."""
     seed(hits=[6, 8, 10, 12] * 10)
     body = client.get("/").text
+    assert '<section class="summary" aria-label="Summary statistics">' in body
+    assert body.count('class="card summary-card"') == 4
     assert "Recent 15-Game Avg" in body
     assert "Season Avg" in body
     assert "vs MLB" in body
diff --git a/tests/test_web_comparison.py b/tests/test_web_comparison.py
index 1a5fcc7..77bb37a 100644
--- a/tests/test_web_comparison.py
+++ b/tests/test_web_comparison.py
@@ -286,6 +286,10 @@ def test_complete_coverage_renders_exact_rolling_indexes_and_four_summary_cards(
     assert traces[2]["y"] == pytest.approx([100.0, 100.0])
 
     cards = summary_card_values(body)
+    assert (
+        '<section class="summary summary--comparison" '
+        'aria-label="Comparison summary statistics">'
+    ) in body
     assert set(cards) == {
         "Recent Hits Index",
         "Recent K Index",
diff --git a/tests/test_web_page_scaffolding.py b/tests/test_web_page_scaffolding.py
index 9862f71..a888c3d 100644
--- a/tests/test_web_page_scaffolding.py
+++ b/tests/test_web_page_scaffolding.py
@@ -336,6 +336,8 @@ def test_empty_database_renders_the_empty_state_with_requested_values(
     assert "--team-id 136 --season 2025" in body
     # No stored team means no selector form to fill in.
     assert '<select id="team_id"' not in body
+    assert 'id="team-seasons-data"' not in body
+    assert "/static/js/season-selector.js" not in body
     assert_navigation(body, current=page, query="window=15")
 
     requested = client.get(f"{path}?team_id=147&season=2023&window=5")
@@ -414,6 +416,14 @@ def test_explicit_selection_is_reflected_in_the_form_and_navigation(
     assert response.status_code == 200
     body = response.text
     assert f'<form class="controls card" method="get" action="{path}">' in body
+    for field in ("team_id", "season", "window"):
+        assert f'<label for="{field}">' in body
+        assert f'<select id="{field}" name="{field}">' in body
+    assert '<img class="control__logo js-logo"' in body
+    assert 'alt=""' in body
+    assert 'id="team-seasons-data"' in body
+    assert "/static/js/season-selector.js" in body
+    assert '<button type="submit">Update chart</button>' in body
     assert f'<option value="{MARINERS_ID}" selected>{MARINERS_NAME}</option>' in body
     assert '<option value="2024" selected>2024</option>' in body
     assert '<option value="5" selected>5 Games</option>' in body

From 6cc0e57252493547b81a655dc6690a96152947c9 Mon Sep 17 00:00:00 2001
From: Matthew Spah <spahmatthew@gmail.com>
Date: Fri, 25 Sep 2026 09:34:56 -0700
Subject: [PATCH 2/2] docs: name team selector partial in strikeouts guide

---
 docs/team-strikeouts-visualization.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/team-strikeouts-visualization.md b/docs/team-strikeouts-visualization.md
index 3f74bef..3fd1516 100644
--- a/docs/team-strikeouts-visualization.md
+++ b/docs/team-strikeouts-visualization.md
@@ -249,8 +249,8 @@ and their labels must stay distinct. A `GenericMetricEngine` would have to
 encode all of that as configuration.
 
 What *is* shared is genuinely shared infrastructure that already existed: the
-team-season selector (`app/web/selection.py`), the selector form partial
-(`_selector_form.html`), figure rendering, and date/matchup formatting.
+team-season selector (`app/web/selection.py`), the Team selector form partial
+(`_team_selector_form.html`), figure rendering, and date/matchup formatting.
 
 ## 10. Legacy null-data behavior