From b2e14b212af0366f84af3d244a643d3be0cc0943 Mon Sep 17 00:00:00 2001
From: Matthew Spah <spahmatthew@gmail.com>
Date: Thu, 24 Sep 2026 09:48:34 -0700
Subject: [PATCH 1/2] feat: group team analytics navigation under Teams

---
 app/web/navigation.py                   |  16 ++-
 app/web/static/css/app.css              | 127 ++++++++++++++++++---
 app/web/templates/_team_navigation.html |  18 +++
 app/web/templates/base.html             |  22 ++--
 app/web/templates/baserunners.html      |   2 +-
 app/web/templates/comparison.html       |   2 +-
 app/web/templates/hits_allowed.html     |   2 +-
 app/web/templates/index.html            |   2 +-
 app/web/templates/pitching.html         |   2 +-
 app/web/templates/run_differential.html |   2 +-
 app/web/templates/runs.html             |   2 +-
 app/web/templates/strikeouts.html       |   2 +-
 app/web/templates/team_base.html        |  10 ++
 docs/ui-information-architecture.md     |  31 +++++
 tests/test_navigation.py                |  24 +++-
 tests/test_web.py                       |  11 +-
 tests/test_web_baserunners.py           |   4 +-
 tests/test_web_page_scaffolding.py      | 146 ++++++++++++++++++------
 tests/test_web_runs.py                  |   2 +-
 19 files changed, 343 insertions(+), 84 deletions(-)
 create mode 100644 app/web/templates/_team_navigation.html
 create mode 100644 app/web/templates/team_base.html
 create mode 100644 docs/ui-information-architecture.md

diff --git a/app/web/navigation.py b/app/web/navigation.py
index 486a7cb..4fc0b33 100644
--- a/app/web/navigation.py
+++ b/app/web/navigation.py
@@ -9,6 +9,7 @@
 """
 
 from dataclasses import dataclass
+from typing import Literal
 from urllib.parse import urlencode
 
 HITS_PATH = "/"
@@ -22,12 +23,12 @@
 
 HITS_LABEL = "Hits"
 STRIKEOUTS_LABEL = "Batting Strikeouts"
-RUNS_LABEL = "Runs"
+RUNS_LABEL = "Runs Scored"
 BASERUNNERS_LABEL = "Baserunners"
 RUN_DIFFERENTIAL_LABEL = "Run Differential"
-PITCHING_LABEL = "Pitching"
+PITCHING_LABEL = "Pitching Trends"
 HITS_ALLOWED_LABEL = "Hits Allowed"
-COMPARISON_LABEL = "Comparison"
+COMPARISON_LABEL = "Hits vs Batting Strikeouts"
 
 
 @dataclass(frozen=True)
@@ -37,6 +38,7 @@ class NavLink:
     label: str
     href: str
     is_current: bool
+    group: Literal["Offense", "Pitching", "Results"]
 
 
 def build_nav_links(
@@ -60,41 +62,49 @@ def build_nav_links(
     return [
         NavLink(
             label=HITS_LABEL,
+            group="Offense",
             href=f"{HITS_PATH}{suffix}",
             is_current=current_path == HITS_PATH,
         ),
         NavLink(
             label=STRIKEOUTS_LABEL,
+            group="Offense",
             href=f"{STRIKEOUTS_PATH}{suffix}",
             is_current=current_path == STRIKEOUTS_PATH,
         ),
         NavLink(
             label=RUNS_LABEL,
+            group="Offense",
             href=f"{RUNS_PATH}{suffix}",
             is_current=current_path == RUNS_PATH,
         ),
         NavLink(
             label=BASERUNNERS_LABEL,
+            group="Offense",
             href=f"{BASERUNNERS_PATH}{suffix}",
             is_current=current_path == BASERUNNERS_PATH,
         ),
         NavLink(
             label=RUN_DIFFERENTIAL_LABEL,
+            group="Results",
             href=f"{RUN_DIFFERENTIAL_PATH}{suffix}",
             is_current=current_path == RUN_DIFFERENTIAL_PATH,
         ),
         NavLink(
             label=PITCHING_LABEL,
+            group="Pitching",
             href=f"{PITCHING_PATH}{suffix}",
             is_current=current_path == PITCHING_PATH,
         ),
         NavLink(
             label=HITS_ALLOWED_LABEL,
+            group="Pitching",
             href=f"{HITS_ALLOWED_PATH}{suffix}",
             is_current=current_path == HITS_ALLOWED_PATH,
         ),
         NavLink(
             label=COMPARISON_LABEL,
+            group="Offense",
             href=f"{COMPARISON_PATH}{suffix}",
             is_current=current_path == COMPARISON_PATH,
         ),
diff --git a/app/web/static/css/app.css b/app/web/static/css/app.css
index c0430f1..8702eee 100644
--- a/app/web/static/css/app.css
+++ b/app/web/static/css/app.css
@@ -86,41 +86,131 @@ body {
   color: #d8e6f2;
 }
 
-/* Navigation */
+/* Primary/domain navigation */
 
-.site-nav {
+.primary-nav {
   display: flex;
   flex-wrap: wrap;
   gap: 0.35rem;
-  max-width: 100%;
 }
 
-.site-nav__link {
+.primary-nav__link {
   display: inline-block;
-  padding: 0.4rem 0.85rem;
-  border-radius: 999px;
-  color: #c8d6e5;
-  font-size: 0.95rem;
+  padding: 0.5rem 0.85rem;
+  border-radius: 8px;
+  color: #ffffff;
   font-weight: 600;
   text-decoration: none;
 }
 
-.site-nav__link:hover {
-  color: #ffffff;
-  background: rgba(255, 255, 255, 0.08);
+.primary-nav__link:hover,
+.primary-nav__link[aria-current="location"] {
+  background: rgba(255, 255, 255, 0.12);
 }
 
-.site-nav__link--current {
-  color: #ffffff;
-  background: rgba(255, 255, 255, 0.12);
+.primary-nav__link[aria-current="location"] {
+  text-decoration: underline;
+  text-underline-offset: 0.3em;
 }
 
 .brand:focus-visible,
-.site-nav__link:focus-visible {
+.primary-nav__link:focus-visible {
   outline: 2px solid #7fd3d4;
   outline-offset: 2px;
 }
 
+/* Team analytics navigation */
+
+.team-nav {
+  background: var(--card-bg);
+  border-bottom: 1px solid var(--border);
+}
+
+.team-nav__groups {
+  display: flex;
+  gap: 1rem 2rem;
+  padding-top: 1rem;
+  padding-bottom: 1rem;
+}
+
+.team-nav__group {
+  min-width: 0;
+  flex: 1 1 0;
+}
+
+.team-nav__group:first-child {
+  flex-grow: 2;
+}
+
+.team-nav__heading {
+  margin: 0 0 0.4rem;
+  color: var(--muted);
+  font-size: 0.8rem;
+  font-weight: 700;
+}
+
+.team-nav__links {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.team-nav__links li {
+  max-width: 100%;
+}
+
+.team-nav__link {
+  display: block;
+  padding: 0.55rem 0.75rem;
+  border-radius: 6px;
+  color: var(--navy);
+  font-size: 0.95rem;
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.team-nav__link:hover {
+  background: var(--page-bg);
+}
+
+.team-nav__link--current {
+  background: var(--navy);
+  color: #ffffff;
+  text-decoration: underline;
+  text-underline-offset: 0.25em;
+}
+
+.team-nav__link--current:hover {
+  background: var(--navy-deep);
+}
+
+.team-nav__link:focus-visible,
+.skip-link:focus-visible,
+#main-content:focus-visible {
+  outline: 3px solid var(--teal-dark);
+  outline-offset: 3px;
+}
+
+/* Keyboard shortcut past both navigation landmarks. */
+.skip-link {
+  position: absolute;
+  top: 0.5rem;
+  left: 0.5rem;
+  z-index: 10;
+  transform: translateY(-200%);
+  padding: 0.75rem 1rem;
+  background: #ffffff;
+  color: var(--navy);
+  font-weight: 700;
+}
+
+.skip-link:focus {
+  transform: translateY(0);
+}
+
 /* Page */
 
 .page {
@@ -488,6 +578,11 @@ body {
 }
 
 @media (max-width: 48rem) {
+  .team-nav__groups {
+    flex-direction: column;
+    gap: 0.75rem;
+  }
+
   /* Only the inline padding changes with width. A `padding` shorthand here
      would also reset the vertical padding `.page` sets. */
   .shell {
@@ -524,7 +619,7 @@ body {
     gap: 0.5rem;
   }
 
-  .site-nav {
+  .primary-nav {
     margin-left: -0.85rem;
   }
 
diff --git a/app/web/templates/_team_navigation.html b/app/web/templates/_team_navigation.html
new file mode 100644
index 0000000..1369946
--- /dev/null
+++ b/app/web/templates/_team_navigation.html
@@ -0,0 +1,18 @@
+<nav class="team-nav" aria-label="Team analytics">
+  <div class="shell team-nav__groups">
+    {% for group in ("Offense", "Pitching", "Results") %}
+      <section class="team-nav__group" aria-labelledby="team-nav-{{ group|lower }}">
+        <h2 class="team-nav__heading" id="team-nav-{{ group|lower }}">{{ group }}</h2>
+        <ul class="team-nav__links">
+          {% for link in nav_links if link.group == group %}
+            <li>
+              <a class="team-nav__link{% if link.is_current %} team-nav__link--current{% endif %}"
+                 href="{{ link.href }}"
+                 {% if link.is_current %}aria-current="page"{% endif %}>{{ link.label }}</a>
+            </li>
+          {% endfor %}
+        </ul>
+      </section>
+    {% endfor %}
+  </div>
+</nav>
diff --git a/app/web/templates/base.html b/app/web/templates/base.html
index 95d1195..ab4bcd9 100644
--- a/app/web/templates/base.html
+++ b/app/web/templates/base.html
@@ -9,9 +9,7 @@
     {% block head %}{% endblock %}
   </head>
   <body>
-    {# One header bar: branding on the left, the real metric navigation on the
-       right. The navigation is the only site-wide control the application
-       actually has, so it fills the space rather than a second stacked bar. #}
+    <a class="skip-link" href="#main-content">Skip to main content</a>
     <header class="site-header">
       <div class="shell site-header__inner">
         <a class="brand" href="/">
@@ -19,19 +17,17 @@
           <img class="brand__logo js-logo" src="{{ mlb_logo_url }}" alt="" width="34" height="34" />
           MLB Stats Visualizer
         </a>
-        {% if nav_links %}
-          <nav class="site-nav" aria-label="Metrics">
-            {%- for link in nav_links %}
-              <a class="site-nav__link{% if link.is_current %} site-nav__link--current{% endif %}"
-                 href="{{ link.href }}"
-                 {% if link.is_current %}aria-current="page"{% endif %}>{{ link.label }}</a>
-            {%- endfor %}
-          </nav>
-        {% endif %}
+        <nav class="primary-nav" aria-label="Primary">
+          {% block primary_navigation %}
+            <a class="primary-nav__link" href="/">Teams</a>
+          {% endblock %}
+        </nav>
       </div>
     </header>
 
-    <main class="shell page">{% block content %}{% endblock %}</main>
+    {% block domain_navigation %}{% endblock %}
+
+    <main id="main-content" class="shell page" tabindex="-1">{% block content %}{% endblock %}</main>
 
     <footer class="site-footer">
       <div class="shell site-footer__inner">
diff --git a/app/web/templates/baserunners.html b/app/web/templates/baserunners.html
index b6fb797..073ed83 100644
--- a/app/web/templates/baserunners.html
+++ b/app/web/templates/baserunners.html
@@ -1,4 +1,4 @@
-{% extends "base.html" %}
+{% extends "team_base.html" %}
 
 {% block title %}
   {%- if state == "ok" -%}
diff --git a/app/web/templates/comparison.html b/app/web/templates/comparison.html
index 71ec379..2281fbd 100644
--- a/app/web/templates/comparison.html
+++ b/app/web/templates/comparison.html
@@ -1,4 +1,4 @@
-{% extends "base.html" %}
+{% extends "team_base.html" %}
 
 {% block title %}
   {%- if state == "ok" -%}
diff --git a/app/web/templates/hits_allowed.html b/app/web/templates/hits_allowed.html
index 6e2b868..6b4e438 100644
--- a/app/web/templates/hits_allowed.html
+++ b/app/web/templates/hits_allowed.html
@@ -1,4 +1,4 @@
-{% extends "base.html" %}
+{% extends "team_base.html" %}
 
 {% block title %}
   {%- if state == "ok" -%}
diff --git a/app/web/templates/index.html b/app/web/templates/index.html
index 0c6628c..b48b2be 100644
--- a/app/web/templates/index.html
+++ b/app/web/templates/index.html
@@ -1,4 +1,4 @@
-{% extends "base.html" %}
+{% extends "team_base.html" %}
 
 {% block title %}
   {%- if state == "ok" -%}
diff --git a/app/web/templates/pitching.html b/app/web/templates/pitching.html
index 3c021ea..ac392eb 100644
--- a/app/web/templates/pitching.html
+++ b/app/web/templates/pitching.html
@@ -1,4 +1,4 @@
-{% extends "base.html" %}
+{% extends "team_base.html" %}
 
 {% block title %}
   {%- if state == "ok" -%}
diff --git a/app/web/templates/run_differential.html b/app/web/templates/run_differential.html
index 38c7940..8f9b537 100644
--- a/app/web/templates/run_differential.html
+++ b/app/web/templates/run_differential.html
@@ -1,4 +1,4 @@
-{% extends "base.html" %}
+{% extends "team_base.html" %}
 
 {% block title %}
   {%- if state == "ok" -%}
diff --git a/app/web/templates/runs.html b/app/web/templates/runs.html
index df7db53..98a006d 100644
--- a/app/web/templates/runs.html
+++ b/app/web/templates/runs.html
@@ -1,4 +1,4 @@
-{% extends "base.html" %}
+{% extends "team_base.html" %}
 
 {% block title %}
   {%- if state == "ok" -%}
diff --git a/app/web/templates/strikeouts.html b/app/web/templates/strikeouts.html
index 5bdf9b7..0cbfc9f 100644
--- a/app/web/templates/strikeouts.html
+++ b/app/web/templates/strikeouts.html
@@ -1,4 +1,4 @@
-{% extends "base.html" %}
+{% extends "team_base.html" %}
 
 {% block title %}
   {%- if state == "ok" -%}
diff --git a/app/web/templates/team_base.html b/app/web/templates/team_base.html
new file mode 100644
index 0000000..92ce7dd
--- /dev/null
+++ b/app/web/templates/team_base.html
@@ -0,0 +1,10 @@
+{% extends "base.html" %}
+
+{% block primary_navigation %}
+  {# Hits is the Team entry point; reuse the scaffold's resolved/requested URL. #}
+  <a class="primary-nav__link" href="{{ nav_links[0].href }}" aria-current="location">Teams</a>
+{% endblock %}
+
+{% block domain_navigation %}
+  {% include "_team_navigation.html" %}
+{% endblock %}
diff --git a/docs/ui-information-architecture.md b/docs/ui-information-architecture.md
new file mode 100644
index 0000000..2413b52
--- /dev/null
+++ b/docs/ui-information-architecture.md
@@ -0,0 +1,31 @@
+# UI information architecture
+
+Issue #30, implementation Slice A separates application domains from Team metrics.
+The primary navigation currently contains only **Teams**. Players stays hidden
+until a real destination exists; no placeholder links or pages are rendered.
+
+Team analytics uses ordinary document links under noninteractive headings:
+
+- **Offense:** Hits (`/`), Batting Strikeouts (`/strikeouts`), Runs Scored
+  (`/runs`), Baserunners (`/baserunners`), Hits vs Batting Strikeouts (`/comparison`).
+- **Pitching:** Pitching Trends (`/pitching`), Hits Allowed (`/hits-allowed`).
+- **Results:** Run Differential (`/run-differential`).
+
+Offense includes broader outcomes than hitting alone. Comparison belongs there
+because it compares hits and batting strikeouts, not arbitrary teams or seasons.
+All existing URLs remain canonical, with no aliases or redirects.
+
+`base.html` owns the entity-neutral shell, primary navigation, skip link, main
+landmark, and footer. `team_base.html` supplies the active Team domain and grouped
+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.
+
+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
+validation and schema errors do not require Team context.
+
+Teams uses `aria-current="location"`; only the current metric uses
+`aria-current="page"`. Groups stack on mobile and links wrap, without navigation
+JavaScript or tab semantics. Selectors and chart-local scrolling are unchanged.
diff --git a/tests/test_navigation.py b/tests/test_navigation.py
index f5e2584..efd8483 100644
--- a/tests/test_navigation.py
+++ b/tests/test_navigation.py
@@ -25,12 +25,12 @@ def test_every_metric_page_is_linked() -> None:
     assert [link.label for link in links] == [
         "Hits",
         "Batting Strikeouts",
-        "Runs",
+        "Runs Scored",
         "Baserunners",
         "Run Differential",
-        "Pitching",
+        "Pitching Trends",
         "Hits Allowed",
-        "Comparison",
+        "Hits vs Batting Strikeouts",
     ]
 
 
@@ -181,3 +181,21 @@ def test_unset_values_are_left_out_of_the_query() -> None:
     assert links[5].href == "/pitching?team_id=136&window=30"
     assert links[6].href == "/hits-allowed?team_id=136&window=30"
     assert links[7].href == "/comparison?team_id=136&window=30"
+
+
+def test_team_metrics_have_explicit_baseball_groups() -> None:
+    links = build_nav_links(current_path=HITS_PATH)
+    assert {
+        group: [link.label for link in links if link.group == group]
+        for group in ("Offense", "Pitching", "Results")
+    } == {
+        "Offense": [
+            "Hits",
+            "Batting Strikeouts",
+            "Runs Scored",
+            "Baserunners",
+            "Hits vs Batting Strikeouts",
+        ],
+        "Pitching": ["Pitching Trends", "Hits Allowed"],
+        "Results": ["Run Differential"],
+    }
diff --git a/tests/test_web.py b/tests/test_web.py
index 93ed8ae..f96d34a 100644
--- a/tests/test_web.py
+++ b/tests/test_web.py
@@ -264,16 +264,19 @@ def test_page_uses_the_product_header(client: TestClient, seed: SeedFn) -> None:
     assert "Team Hitting Trends" in body
 
 
-def test_the_navigation_sits_inside_the_single_header_bar(
+def test_the_header_separates_domain_navigation_from_team_metrics(
     client: TestClient, seed: SeedFn
 ) -> None:
-    """One header bar carries both the branding and the metric navigation."""
+    """The global header identifies the domain; metrics live below it."""
     seed(hits=[7] * 20)
     body = client.get("/").text
     header = body[body.index('class="site-header"') : body.index("</header>")]
     assert "MLB Stats Visualizer" in header
-    assert 'aria-label="Metrics"' in header
-    assert "Batting Strikeouts</a>" in header
+    assert 'aria-label="Primary"' in header
+    assert 'aria-current="location">Teams</a>' in header
+    assert "Batting Strikeouts</a>" not in header
+    assert 'aria-label="Team analytics"' in body
+    assert "Batting Strikeouts</a>" in body
 
 
 def test_the_selector_shows_the_club_logo_for_the_selected_team(
diff --git a/tests/test_web_baserunners.py b/tests/test_web_baserunners.py
index cdb3827..95261be 100644
--- a/tests/test_web_baserunners.py
+++ b/tests/test_web_baserunners.py
@@ -384,8 +384,8 @@ def test_the_baserunners_page_links_back_to_the_other_pages(
     body = client.get("/baserunners").text
     assert ">Hits</a>" in body
     assert "Batting Strikeouts</a>" in body
-    assert ">Runs</a>" in body
-    assert ">Comparison</a>" in body
+    assert ">Runs Scored</a>" in body
+    assert ">Hits vs Batting Strikeouts</a>" in body
 
 
 def test_navigation_marks_the_baserunners_page_as_current(
diff --git a/tests/test_web_page_scaffolding.py b/tests/test_web_page_scaffolding.py
index 4531624..c01b993 100644
--- a/tests/test_web_page_scaffolding.py
+++ b/tests/test_web_page_scaffolding.py
@@ -16,10 +16,9 @@
 the assertions for one route and one state rather than one assertion apiece.
 """
 
-import html
-import re
 from collections.abc import Callable, Generator, Iterator
 from dataclasses import dataclass
+from html.parser import HTMLParser
 from pathlib import Path
 from urllib.parse import urlencode
 
@@ -60,12 +59,14 @@ class AnalyticsPage:
 PAGES = (
     AnalyticsPage("/", "Team Hitting Trends", "Hits"),
     AnalyticsPage("/strikeouts", "Team Batting Strikeout Trends", "Batting Strikeouts"),
-    AnalyticsPage("/runs", "Team Run Scoring Trends", "Runs"),
+    AnalyticsPage("/runs", "Team Run Scoring Trends", "Runs Scored"),
     AnalyticsPage("/baserunners", "Team Baserunners Trends", "Baserunners"),
     AnalyticsPage("/run-differential", "Team Run Differential", "Run Differential"),
-    AnalyticsPage("/pitching", "Team Pitching Trends", "Pitching"),
+    AnalyticsPage("/pitching", "Team Pitching Trends", "Pitching Trends"),
     AnalyticsPage("/hits-allowed", "Team Hits Allowed Trends", "Hits Allowed"),
-    AnalyticsPage("/comparison", "Team Hitting Trends Comparison", "Comparison"),
+    AnalyticsPage(
+        "/comparison", "Team Hitting Trends Comparison", "Hits vs Batting Strikeouts"
+    ),
 )
 PAGE_PATHS = tuple(page.path for page in PAGES)
 
@@ -103,39 +104,97 @@ def page_for(path: str) -> AnalyticsPage:
 
 # --- Navigation assertion helpers ---------------------------------------------
 
-_NAV_LINK_PATTERN = re.compile(
-    r'<a class="site-nav__link(?P<current> site-nav__link--current)?"\s+'
-    r'href="(?P<href>[^"]*)"\s*(?:aria-current="page")?>(?P<label>[^<]+)</a>'
-)
-
 
-@dataclass(frozen=True)
-class RenderedNavLink:
-    label: str
-    href: str
-    is_current: bool
-
-
-def rendered_nav_links(body: str) -> list[RenderedNavLink]:
-    links = [
-        RenderedNavLink(
-            label=match.group("label"),
-            href=html.unescape(match.group("href")),
-            is_current=match.group("current") is not None,
-        )
-        for match in _NAV_LINK_PATTERN.finditer(body)
-    ]
-    assert len(links) == len(PAGES), "the page did not render the full navigation"
-    return links
+class NavigationParser(HTMLParser):
+    """Read semantic navigation independently of CSS classes and whitespace."""
+
+    def __init__(self, body: str) -> None:
+        super().__init__()
+        self.landmarks: dict[str, list[dict[str, str]]] = {}
+        self.headings: list[str] = []
+        self.main_ids: list[str | None] = []
+        self.skip_target: str | None = None
+        self.current_pages = 0
+        self.tabs = False
+        self._nav: str | None = None
+        self._link: dict[str, str] | None = None
+        self._heading = False
+        self.feed(body)
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        attributes = dict(attrs)
+        if attributes.get("aria-current") == "page":
+            self.current_pages += 1
+        if attributes.get("role") in ("tab", "tablist"):
+            self.tabs = True
+        if tag == "nav":
+            self._nav = attributes.get("aria-label")
+            assert self._nav, "navigation landmarks need accessible names"
+            self.landmarks[self._nav] = []
+        if tag == "main":
+            self.main_ids.append(attributes.get("id"))
+        if tag == "a":
+            if attributes.get("class") == "skip-link":
+                self.skip_target = attributes.get("href")
+            if self._nav:
+                assert not self._heading, "group headings must not be links"
+                self._link = {
+                    "label": "",
+                    "href": attributes.get("href") or "",
+                    "current": attributes.get("aria-current") or "",
+                }
+                self.landmarks[self._nav].append(self._link)
+        if tag == "h2" and self._nav == "Team analytics":
+            assert self._link is None, "group headings must not be links"
+            self._heading = True
+            self.headings.append("")
+
+    def handle_data(self, data: str) -> None:
+        if self._link is not None:
+            self._link["label"] += data.strip()
+        if self._heading:
+            self.headings[-1] += data.strip()
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag == "nav":
+            self._nav = None
+        if tag == "a":
+            self._link = None
+        if tag == "h2":
+            self._heading = False
 
 
 def assert_navigation(body: str, *, current: AnalyticsPage, query: str) -> None:
-    """Every link carries ``query``, and only ``current`` is marked current."""
+    """Every link carries the selection; domain and document states differ."""
     suffix = f"?{query}" if query else ""
-    links = rendered_nav_links(body)
-    assert [link.href for link in links] == [f"{page.path}{suffix}" for page in PAGES]
-    assert [link.label for link in links if link.is_current] == [current.nav_label]
-    assert body.count('aria-current="page"') == 1
+    navigation = NavigationParser(body)
+    assert list(navigation.landmarks) == ["Primary", "Team analytics"]
+    assert navigation.landmarks["Primary"] == [
+        {"label": "Teams", "href": f"/{suffix}", "current": "location"}
+    ]
+    order = (
+        "/",
+        "/strikeouts",
+        "/runs",
+        "/baserunners",
+        "/comparison",
+        "/pitching",
+        "/hits-allowed",
+        "/run-differential",
+    )
+    assert navigation.landmarks["Team analytics"] == [
+        {
+            "label": page_for(path).nav_label,
+            "href": f"{path}{suffix}",
+            "current": "page" if path == current.path else "",
+        }
+        for path in order
+    ]
+    assert navigation.headings == ["Offense", "Pitching", "Results"]
+    assert navigation.current_pages == 1
+    assert not navigation.tabs
+    assert navigation.skip_target == "#main-content"
+    assert navigation.main_ids == ["main-content"]
 
 
 def expected_query(team_id: int | None, season: int | None, window: int) -> str:
@@ -404,6 +463,7 @@ def test_invalid_query_values_are_rejected_by_fastapi_validation(
         assert "That link has a value this page cannot use" in browser_response.text
         assert f"{parameter}: " in browser_response.text, url
         assert "Traceback" not in browser_response.text, url
+        assert "Team analytics" not in NavigationParser(browser_response.text).landmarks
 
     window_response = client.get(f"{path}?window=7", headers=BROWSER_HEADERS)
     assert "Input should be 5, 10, 15 or 30" in window_response.text
@@ -425,7 +485,8 @@ def test_missing_schema_renders_the_migration_error_page(
     # error.html, not the route template: no page heading, selector, or nav.
     assert f"<h1>{page_for(path).heading}</h1>" not in body
     assert '<select id="team_id"' not in body
-    assert 'aria-label="Metrics"' not in body
+    assert "Team analytics" not in NavigationParser(body).landmarks
+    assert NavigationParser(body).current_pages == 0
 
 
 # --- DB-only browser rendering ------------------------------------------------
@@ -455,3 +516,20 @@ def fail(*args: object, **kwargs: object) -> None:
     )
     assert response.status_code == 200
     assert SEEDED_OUTCOMES[path] in response.text
+
+
+@pytest.mark.parametrize(
+    "path",
+    ("/strikeouts", "/baserunners", "/run-differential", "/pitching", "/hits-allowed"),
+)
+def test_reimport_states_keep_team_navigation(
+    client: TestClient, session_factory: Callable[[], Session], path: str
+) -> None:
+    with session_factory() as session:
+        upsert_team_season(session, lines=make_season(hits=[8] * GAMES))
+        session.commit()
+    response = client.get(f"{path}?team_id=136&season=2025&window=10")
+    assert response.status_code == 409
+    assert_navigation(
+        response.text, current=page_for(path), query=expected_query(136, 2025, 10)
+    )
diff --git a/tests/test_web_runs.py b/tests/test_web_runs.py
index 6982e7f..f485fce 100644
--- a/tests/test_web_runs.py
+++ b/tests/test_web_runs.py
@@ -375,7 +375,7 @@ def test_every_page_links_to_runs(client: TestClient, seed: SeedFn) -> None:
     for path in ("/", "/strikeouts", "/runs"):
         body = client.get(path).text
         assert 'href="/runs' in body
-        assert ">Runs</a>" in body
+        assert ">Runs Scored</a>" in body
 
 
 def test_the_runs_page_links_back_to_the_other_pages(

From 277b3abe30c3734a4459c4ef3cd3575ab158003e Mon Sep 17 00:00:00 2001
From: Matthew Spah <spahmatthew@gmail.com>
Date: Fri, 25 Sep 2026 07:19:23 -0700
Subject: [PATCH 2/2] fix: simplify team navigation group semantics

---
 app/web/templates/_team_navigation.html |  6 ++---
 tests/test_web_page_scaffolding.py      | 30 ++++++++++++++-----------
 2 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/app/web/templates/_team_navigation.html b/app/web/templates/_team_navigation.html
index 1369946..bc981fa 100644
--- a/app/web/templates/_team_navigation.html
+++ b/app/web/templates/_team_navigation.html
@@ -1,8 +1,8 @@
 <nav class="team-nav" aria-label="Team analytics">
   <div class="shell team-nav__groups">
     {% for group in ("Offense", "Pitching", "Results") %}
-      <section class="team-nav__group" aria-labelledby="team-nav-{{ group|lower }}">
-        <h2 class="team-nav__heading" id="team-nav-{{ group|lower }}">{{ group }}</h2>
+      <div class="team-nav__group">
+        <p class="team-nav__heading">{{ group }}</p>
         <ul class="team-nav__links">
           {% for link in nav_links if link.group == group %}
             <li>
@@ -12,7 +12,7 @@ <h2 class="team-nav__heading" id="team-nav-{{ group|lower }}">{{ group }}</h2>
             </li>
           {% endfor %}
         </ul>
-      </section>
+      </div>
     {% endfor %}
   </div>
 </nav>
diff --git a/tests/test_web_page_scaffolding.py b/tests/test_web_page_scaffolding.py
index c01b993..9862f71 100644
--- a/tests/test_web_page_scaffolding.py
+++ b/tests/test_web_page_scaffolding.py
@@ -106,19 +106,19 @@ def page_for(path: str) -> AnalyticsPage:
 
 
 class NavigationParser(HTMLParser):
-    """Read semantic navigation independently of CSS classes and whitespace."""
+    """Read navigation semantics and the focused group-label markup."""
 
     def __init__(self, body: str) -> None:
         super().__init__()
         self.landmarks: dict[str, list[dict[str, str]]] = {}
-        self.headings: list[str] = []
+        self.group_labels: list[str] = []
         self.main_ids: list[str | None] = []
         self.skip_target: str | None = None
         self.current_pages = 0
         self.tabs = False
         self._nav: str | None = None
         self._link: dict[str, str] | None = None
-        self._heading = False
+        self._group_label = False
         self.feed(body)
 
     def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
@@ -137,31 +137,35 @@ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None
             if attributes.get("class") == "skip-link":
                 self.skip_target = attributes.get("href")
             if self._nav:
-                assert not self._heading, "group headings must not be links"
+                assert not self._group_label, "group labels must not be links"
                 self._link = {
                     "label": "",
                     "href": attributes.get("href") or "",
                     "current": attributes.get("aria-current") or "",
                 }
                 self.landmarks[self._nav].append(self._link)
-        if tag == "h2" and self._nav == "Team analytics":
-            assert self._link is None, "group headings must not be links"
-            self._heading = True
-            self.headings.append("")
+        if (
+            tag == "p"
+            and attributes.get("class") == "team-nav__heading"
+            and self._nav == "Team analytics"
+        ):
+            assert self._link is None, "group labels must not be links"
+            self._group_label = True
+            self.group_labels.append("")
 
     def handle_data(self, data: str) -> None:
         if self._link is not None:
             self._link["label"] += data.strip()
-        if self._heading:
-            self.headings[-1] += data.strip()
+        if self._group_label:
+            self.group_labels[-1] += data.strip()
 
     def handle_endtag(self, tag: str) -> None:
         if tag == "nav":
             self._nav = None
         if tag == "a":
             self._link = None
-        if tag == "h2":
-            self._heading = False
+        if tag == "p":
+            self._group_label = False
 
 
 def assert_navigation(body: str, *, current: AnalyticsPage, query: str) -> None:
@@ -190,7 +194,7 @@ def assert_navigation(body: str, *, current: AnalyticsPage, query: str) -> None:
         }
         for path in order
     ]
-    assert navigation.headings == ["Offense", "Pitching", "Results"]
+    assert navigation.group_labels == ["Offense", "Pitching", "Results"]
     assert navigation.current_pages == 1
     assert not navigation.tabs
     assert navigation.skip_target == "#main-content"