brain-of-reese/.agents/phases/todo/116_modal_scrollbar_theme/00_phase.md

Phase 116 — Document modal: themed code-block scrollbar (TODO L3)

Source: TODO.md L88–99 — "L3 — Document modal: native unstyled horizontal scrollbar in the code block (cosmetic) (2026-09-15, brain-of-reese interactive test)" Story: document-viewer.md — the modal belongs to the document-viewer story (the same-page chip viewer, phase 26). Context: The document modal (the almost-fullscreen chip viewer, .doc-modal — frontend/assets/styles.css:4117+) shows the raw content in a code block; long lines (e.g. a quest::say(...) line in a quest .pl file) overflow horizontally and reveal the browser-native, unstyled scrollbar (light-gray bar) — it clashes with the dark theme, and long lines clip at the right edge.

Objective

The modal's code block scrolls horizontally with a themed scrollbar (scrollbar-color for Firefox, ::-webkit-scrollbar pseudos for Chromium), consistent with the dark theme; long lines stay unwrapped (code stays code) and scroll instead of clipping.

Dependencies

• 115_doc_draft_discard (todo) — pipeline predecessor (execution order) only; no code dependency (CSS + one E2E file).

Design (shared by all tasks — the executor reads this, not the chat)

• Theme tokens (task 01): two CSS custom properties in the theme's token block: --scrollbar-thumb (a muted theme color, ≥3:1 against the track — a scrollbar is a UI component, non-text contrast AA) and --scrollbar-track (near the code-block background). Scope: the modal's raw-content code element only (confirm the exact selector from frontend/assets/document-modal.js / the .doc-modal rules) — no global scrollbar restyle (out of scope; the TODO asks only about the modal).
• Rules (task 01): on the modal code block: overflow-x: auto (confirm present — add if the element relies on an ancestor), scrollbar-width: thin, scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track) (Firefox), and the Chromium pair: ::-webkit-scrollbar { height: 8px }, ::-webkit-scrollbar-track { background: var(--scrollbar-track) }, ::-webkit-scrollbar-thumb { background: var(--scrollbar-thumb); border-radius: 4px }.
• E2E (task 02): the document-viewer story gains a check: open the modal on a document with a long line → the code block is horizontally scrollable (scrollWidth > clientWidth; a scroll action moves it) → a screenshot to .agents/screenshots/ (house convention) as the visual record.

Tasks

1. 01_themed_scrollbar.md — the theme tokens + the scoped scrollbar rules.
2. 02_scrollbar_e2e_check.md — the E2E scroll check + screenshot.

Testing & Quality

• E2E: tests/e2e/test_document_viewer.py (existing — extend, task 02); run in isolation: uv run pytest tests/e2e/test_document_viewer.py -v --no-cov.
• CSS: no unit layer for CSS — the E2E check + screenshot are the gate; the dark-theme suite (tests/e2e/test_dark_tech_theme.py) must stay green (no token collision).
• Coverage: n/a (no app/ code change) — the validate.sh gate stays green.

Completion Criteria

• The modal's code block scrolls horizontally; the scrollbar is themed — the screenshot in .agents/screenshots/ shows no native light-gray bar.
• No global scrollbar change (the new selector is scoped under .doc-modal — grep); the other pages are visually unchanged (regression suites green).
• uv run pytest green; coverage >90%; the e2e file green in isolation; uv run ruff check . && uv run pyright clean.
• One --no-gpg-sign commit; phase dir moved to complete/ by the pipeline gate.

Locked decisions

• A1 — keep horizontal scroll (NO line-wrap) for the code content (owner-confirmed 2026-09-14, roadmap confirmation — the TODO's "consider wrapping long lines per content type" is rejected for code: wrapping breaks code readability; the themed scrollbar is the fix).

Commit

git add frontend/ tests/ .agents/phases/ && git commit --no-gpg-sign -m "style(ui): theme the document modal's code-block horizontal scrollbar (scrollbar-color + webkit pseudos)"