feat(web): 2x reading column on wide desktops — 92rem at >=1500px (chat, shared, document view)

2026-09-01 00:39:19 -04:00
parent 140b97ebf3
commit 7b7a834a1a
5 changed files with 727 additions and 34 deletions
@@ -0,0 +1,197 @@
+"""Unit: the 2x reading column on wide desktops (phase 58, task 01).
+
+The measured-width browser proof is E2E-gated by the phase-58 story
+suite (task 02); like the other frontend-adjacent unit files (the
+test_save_chat_ui.py pattern), this module pins the styles.css markers
+the wide-column contract depends on, so a silent regression is caught
+without a browser:
+
+* the ``--chat-column`` custom property in ``:root`` — 46rem base
+  (the PLAN §7 column lineage) with the provenance comment (owner
+  instruction 2026-08-31, TODO L5 / D2);
+* the ``@media (min-width: 1500px)`` block at the bottom of the
+  responsive region — the SINGLE place that doubles the token to
+  92rem (2x);
+* the four reading-column selectors — ``.chat-shell``,
+  ``.shared-shell``, ``.doc-md``, ``.doc-summary:has(+ .doc-md)`` —
+  each capped with ``max-width: var(--chat-column)`` and NOTHING else
+  in the file uses the token (exactly four rules);
+* the negative pin — ``.tuning-shell`` (a form, not a reading
+  surface) keeps its hard-coded ``max-width: 46rem`` at every width,
+  and it is the only literal ``max-width: 46rem`` rule left in the
+  file;
+* the "46rem column contract" block comments were updated to name the
+  base value + the wide override (the stale "≤46rem" contract claims
+  are gone from the reading-column comments).
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+FRONTEND = Path(__file__).resolve().parents[2] / "frontend"
+STYLES_CSS = FRONTEND / "assets" / "styles.css"
+
+
+def _css() -> str:
+    return STYLES_CSS.read_text(encoding="utf-8")
+
+
+def _rule_block(css: str, selector: str) -> str:
+    """The declaration block of a top-level (or nested) rule: the
+    ``{…}`` following ``selector`` via balanced-brace counting."""
+    m = re.search(rf"^{re.escape(selector)} \{{", css, re.MULTILINE)
+    assert m, f"styles.css must define a rule for {selector}"
+    start = css.index("{", m.start())
+    depth = 0
+    for i in range(start, len(css)):
+        if css[i] == "{":
+            depth += 1
+        elif css[i] == "}":
+            depth -= 1
+            if depth == 0:
+                return css[start : i + 1]
+    raise AssertionError(f"unbalanced braces in the {selector} rule")
+
+
+# ---------- the --chat-column token ----------
+
+
+def test_root_declares_chat_column_46rem_base() -> None:
+    """:root declares --chat-column: 46rem (the PLAN §7 base) with the
+    owner-provenance comment (instruction 2026-08-31, TODO L5)."""
+    css = _css()
+    root = _rule_block(css, ":root")
+    assert "--chat-column: 46rem" in root, (
+        ":root must declare the --chat-column base (46rem)"
+    )
+    pre = css[: css.index("--chat-column: 46rem")]
+    comment = pre[pre.rindex("/*") : pre.rindex("*/")]
+    assert "owner instruction 2026-08-31" in comment, (
+        "the token's comment must cite the owner instruction "
+        "(2026-08-31, TODO L5)"
+    )
+
+
+def test_wide_media_block_doubles_the_token() -> None:
+    """A @media (min-width: 1500px) block sets --chat-column: 92rem on
+    :root — the single wide override (2x the base)."""
+    css = _css()
+    m = re.search(r"@media \(min-width: 1500px\) \{", css)
+    assert m, "styles.css must carry the @media (min-width: 1500px) block"
+    start = css.index("{", m.start())
+    depth = 0
+    for i in range(start, len(css)):
+        if css[i] == "{":
+            depth += 1
+        elif css[i] == "}":
+            depth -= 1
+            if depth == 0:
+                block = css[m.start() : i + 1]
+                break
+    else:
+        raise AssertionError("unbalanced braces in the wide media block")
+    assert ":root { --chat-column: 92rem; }" in block, (
+        "the wide block must set :root { --chat-column: 92rem; }"
+    )
+    # The wide block is the ONLY min-width:1500 media in the file and
+    # the only place 92rem is assigned to the token.
+    assert css.count("@media (min-width: 1500px)") == 1
+    assert css.count("--chat-column: 92rem") == 1
+
+
+def test_wide_block_lives_in_the_bottom_responsive_region() -> None:
+    """The min-width sibling sits alongside the max-width responsive
+    blocks at the bottom of the file (after the <=640px block)."""
+    css = _css()
+    wide = css.index("@media (min-width: 1500px)")
+    mobile = css.rindex("@media (max-width: 640px)")
+    assert wide > mobile, (
+        "the wide override belongs in the bottom media-query region"
+    )
+
+
+# ---------- the four reading-column selectors ----------
+
+
+def test_the_four_reading_columns_use_the_token() -> None:
+    """.chat-shell, .shared-shell, .doc-md and
+    .doc-summary:has(+ .doc-md) each cap with
+    max-width: var(--chat-column) — and exactly those four rules use
+    the token (no other selector)."""
+    css = _css()
+    for selector in (
+        ".chat-shell",
+        ".shared-shell",
+        ".doc-md",
+        ".doc-summary:has(+ .doc-md)",
+    ):
+        assert "max-width: var(--chat-column)" in _rule_block(css, selector), (
+            f"{selector} must cap with max-width: var(--chat-column)"
+        )
+    assert css.count("max-width: var(--chat-column)") == 4, (
+        "exactly the four reading-column selectors use the token"
+    )
+
+
+def test_shared_shell_keeps_the_centered_column_comment() -> None:
+    """.shared-shell's inline comment keeps the "centered chat column"
+    wording and notes the wide override (task 01 work item)."""
+    css = _css()
+    rule = css[css.index(".shared-shell {") : css.index(".shared-shell {") + 400]
+    assert "the PLAN §7 centered chat column" in rule
+    assert "92rem at >=1500px" in rule, "the comment must note the wide override"
+
+
+def test_doc_md_keeps_width_100_under_the_cap() -> None:
+    """.doc-md stays width:100% under the token cap (the modal's
+    1100px panel remains its effective ceiling there)."""
+    assert "width: 100%" in _rule_block(_css(), ".doc-md")
+
+
+# ---------- the negative pins ----------
+
+
+def test_tuning_shell_stays_hardcoded_46rem() -> None:
+    """.tuning-shell (the form column, out of scope) keeps its
+    hard-coded max-width: 46rem at every width — it never widens."""
+    css = _css()
+    tuning = _rule_block(css, ".tuning-shell")
+    assert "max-width: 46rem" in tuning, (
+        ".tuning-shell must stay hard-coded 46rem (negative pin)"
+    )
+    assert "var(--chat-column)" not in tuning, (
+        ".tuning-shell must NOT reference the reading-column token"
+    )
+
+
+def test_no_other_hardcoded_46rem_rule_remains() -> None:
+    """After the switch, the .tuning-shell rule is the ONLY rule with
+    a literal max-width: 46rem — every reading column rides the
+    token (the --chat-column base declaration is the other
+    non-rule occurrence of 46rem)."""
+    css = _css()
+    assert css.count("max-width: 46rem") == 1, (
+        "only .tuning-shell may keep a literal max-width: 46rem"
+    )
+    assert "max-width: 46rem" in _rule_block(css, ".tuning-shell")
+
+
+def test_comments_cite_the_wide_override_with_provenance() -> None:
+    """The block comments that claimed the "46rem column contract" now
+    name base 46rem + the 2x wide override, with the owner
+    instruction (2026-08-31, TODO L5) as the provenance at the token
+    and the media block."""
+    css = _css()
+    # The stale "≤46rem" contract claims are gone from the file.
+    assert "≤46rem" not in css, (
+        "the stale '≤46rem' contract wording must be updated"
+    )
+    # Provenance at the two authoritative spots (token + wide block).
+    token_idx = css.index("--chat-column: 46rem")
+    wide_idx = css.index("@media (min-width: 1500px)")
+    assert "owner instruction 2026-08-31" in css[max(0, token_idx - 400) : token_idx]
+    assert "owner instruction 2026-08-31" in css[max(0, wide_idx - 500) : wide_idx]
+    # The chat-shell comment names base + override.
+    chat_comment = css[: css.index(".chat-shell {")]
+    assert "46rem base" in chat_comment and "92rem" in chat_comment