[PR #1405] [MERGED] PR-2: Visual polish (announcement bars, theme persistence, dev-mirror fix, audit script) #8172

New Issue

GiteaMirror · 2026-04-27T17:28:35-05:00

GiteaMirror commented

2026-04-27 17:28:35 -05:00

📋 Pull Request Information

Original PR: https://github.com/harvard-edge/cs249r_book/pull/1405
Author: @profvjreddi
Created: 4/19/2026
Status: ✅ Merged
Merged: 4/20/2026
Merged by: @profvjreddi

Base: dev ← Head: release-prep/visual-polish

📝 Commits (4)

59e6c64 fix(dev-mirror): compute prefix from dev-side depth in rewrite-dev-urls.sh
0376381 feat(book): per-volume announcement bars (Crimson / ETH-Blue)
33a4a52 feat(theme): cross-site dark-mode persistence + FOUC guard
83f249c test(audit): Playwright site-audit script (sidebar / darkmode / assets)

📊 Changes

11 files changed (+557 additions, -32 deletions)

View changed files

📝 .github/scripts/rewrite-dev-urls.sh (+32 -8)
📝 book/quarto/config/_quarto-html-vol1.yml (+1 -1)
📝 book/quarto/config/_quarto-html-vol2.yml (+1 -1)
➕ book/quarto/config/shared/html/announcement-vol1.yml (+24 -0)
➕ book/quarto/config/shared/html/announcement-vol2.yml (+24 -0)
📝 book/quarto/config/shared/html/announcement.yml (+12 -13)
📝 interviews/staffml/public/theme-bootstrap.js (+26 -8)
📝 interviews/staffml/src/components/ThemeProvider.tsx (+18 -1)
📝 shared/config/site-head.html (+46 -0)
➕ shared/scripts/site-audit.mjs (+269 -0)
➕ shared/scripts/theme-persist.js (+104 -0)

📄 Description

Summary

Visible-on-the-dev-mirror improvements that close several of the
visual/UX gaps the maintainer flagged during the staged-rollout review.
Independent of PR-1 (the safety-net) — can be merged in either order.

What's in this PR

Per-volume announcement bars (Crimson / ETH-Blue). The shared
announcement.yml was a single voice for both volumes; Vol II should
read in the ETH-Blue accent (since it's Machine Learning Systems at
Scale). Split into:

book/quarto/config/shared/html/announcement-vol1.yml (Vol I,
inherits Harvard Crimson via theme accent)
book/quarto/config/shared/html/announcement-vol2.yml (Vol II,
inherits ETH Blue)
The legacy file is left in place as a deprecated no-op pointing at
the two new files. Vol I and Vol II _quarto-html-vol{1,2}.yml
configs now reference the right one.

Cross-site dark-mode persistence + FOUC guard. Today, switching
dark mode on Vol I doesn't carry to TinyTorch / labs / kits / staffml
because each subsite tracks its own preference. New
shared/scripts/theme-persist.js (inlined into
shared/config/site-head.html so it runs synchronously in <head>,
no FOUC) reads quarto-color-scheme from localStorage and applies
data-bs-theme / data-quarto-color-scheme /
html.style.colorScheme before first paint. StaffML's
ThemeProvider.tsx and theme-bootstrap.js updated to read/write
the same key as a fallback so the Next.js property participates in
the shared preference. Listens for storage events too, so a tab that
toggles dark mode propagates to other open tabs in the same domain.

Dev-mirror nested-path bug fix. rewrite-dev-urls.sh had a
hard-coded PREFIX="../" which broke nested subsites like
book/vol1/ and book/vol2/ — they were getting URLs that walked
up one too few directories. Fixed to compute PREFIX from the
actual depth of the subsite's dev-side path. Also fixed an
associative-array key check that wasn't portable to the macOS
default bash 3.2.

Playwright audit script (subcommands: sidebar / darkmode /
assets). New shared/scripts/site-audit.mjs that opens each
deployed subsite in a headless browser and:

sidebar — verifies every Quarto subsite has a visible sidebar
(was missing on a few Vol I / Vol II combinations after the
split).
darkmode — toggles dark mode, screenshots before/after,
flags pages that don't repaint cleanly.
assets — fetches every <img src> and <link rel="stylesheet">
and reports broken ones (catches the "PDF viewer iframe shows a
404" class of issue the maintainer flagged).
Output goes to .audit/ (added to .gitignore in PR-3).

Risk surface

The announcement bar change is purely additive (new files; old file
defanged but not deleted, so any forgotten reference still resolves).
The theme-persist script is <head>-inlined, so it runs before any
user-visible content. Worst case if the script throws: nothing
happens, the user falls back to OS preference (which is the current
behavior).
The rewrite-dev-urls fix has been smoke-tested against vol1/vol2
paths and the depth math verified; included a comment in the script
explaining the depth derivation.
The Playwright script is opt-in (run via node shared/scripts/site-audit.mjs <cmd>);
no CI integration in this PR.

Test plan

CI: book-validate-dev passes (announcement files parse as YAML).
Local: node shared/scripts/site-audit.mjs sidebar produces
a JSON report covering vol1, vol2, tinytorch, labs, kits,
slides, instructors, mlsysim, site, staffml.
Manual: dev mirror Vol II shows ETH-Blue announcement.
Manual: toggle dark mode on Vol I, navigate to TinyTorch,
verify dark mode is preserved (no flash of light theme).

Followup

Wire the audit script into a scheduled GitHub workflow (PR-3 has
the dedup-finder follow-up; the audit script could share the same
workflow shell).
Vol I announcement copy still reads "the unified Volume I/II
edition is rolling out"; tighten language for actual launch.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/harvard-edge/cs249r_book/pull/1405 **Author:** [@profvjreddi](https://github.com/profvjreddi) **Created:** 4/19/2026 **Status:** ✅ Merged **Merged:** 4/20/2026 **Merged by:** [@profvjreddi](https://github.com/profvjreddi) **Base:** `dev` ← **Head:** `release-prep/visual-polish` --- ### 📝 Commits (4) - [`59e6c64`](https://github.com/harvard-edge/cs249r_book/commit/59e6c64ad0ea4c7c9f34f6173c31d6aec0ab6fee) fix(dev-mirror): compute prefix from dev-side depth in rewrite-dev-urls.sh - [`0376381`](https://github.com/harvard-edge/cs249r_book/commit/03763813c7087167114e4c94e4ad81b38c3836ce) feat(book): per-volume announcement bars (Crimson / ETH-Blue) - [`33a4a52`](https://github.com/harvard-edge/cs249r_book/commit/33a4a5283d694601ba398eaa786854e2f95d721f) feat(theme): cross-site dark-mode persistence + FOUC guard - [`83f249c`](https://github.com/harvard-edge/cs249r_book/commit/83f249c53ad04659fbb9afeaa3daaa98db0df7cb) test(audit): Playwright site-audit script (sidebar / darkmode / assets) ### 📊 Changes **11 files changed** (+557 additions, -32 deletions) <details> <summary>View changed files</summary> 📝 `.github/scripts/rewrite-dev-urls.sh` (+32 -8) 📝 `book/quarto/config/_quarto-html-vol1.yml` (+1 -1) 📝 `book/quarto/config/_quarto-html-vol2.yml` (+1 -1) ➕ `book/quarto/config/shared/html/announcement-vol1.yml` (+24 -0) ➕ `book/quarto/config/shared/html/announcement-vol2.yml` (+24 -0) 📝 `book/quarto/config/shared/html/announcement.yml` (+12 -13) 📝 `interviews/staffml/public/theme-bootstrap.js` (+26 -8) 📝 `interviews/staffml/src/components/ThemeProvider.tsx` (+18 -1) 📝 `shared/config/site-head.html` (+46 -0) ➕ `shared/scripts/site-audit.mjs` (+269 -0) ➕ `shared/scripts/theme-persist.js` (+104 -0) </details> ### 📄 Description ## Summary Visible-on-the-dev-mirror improvements that close several of the visual/UX gaps the maintainer flagged during the staged-rollout review. Independent of PR-1 (the safety-net) — can be merged in either order. ### What's in this PR **Per-volume announcement bars (Crimson / ETH-Blue).** The shared `announcement.yml` was a single voice for both volumes; Vol II should read in the ETH-Blue accent (since it's *Machine Learning Systems at Scale*). Split into: - `book/quarto/config/shared/html/announcement-vol1.yml` (Vol I, inherits Harvard Crimson via theme accent) - `book/quarto/config/shared/html/announcement-vol2.yml` (Vol II, inherits ETH Blue) The legacy file is left in place as a deprecated no-op pointing at the two new files. Vol I and Vol II `_quarto-html-vol{1,2}.yml` configs now reference the right one. **Cross-site dark-mode persistence + FOUC guard.** Today, switching dark mode on Vol I doesn't carry to TinyTorch / labs / kits / staffml because each subsite tracks its own preference. New `shared/scripts/theme-persist.js` (inlined into `shared/config/site-head.html` so it runs synchronously in `<head>`, no FOUC) reads `quarto-color-scheme` from `localStorage` and applies `data-bs-theme` / `data-quarto-color-scheme` / `html.style.colorScheme` before first paint. StaffML's `ThemeProvider.tsx` and `theme-bootstrap.js` updated to read/write the same key as a fallback so the Next.js property participates in the shared preference. Listens for storage events too, so a tab that toggles dark mode propagates to other open tabs in the same domain. **Dev-mirror nested-path bug fix.** `rewrite-dev-urls.sh` had a hard-coded `PREFIX="../"` which broke nested subsites like `book/vol1/` and `book/vol2/` — they were getting URLs that walked up one too few directories. Fixed to compute `PREFIX` from the actual depth of the subsite's dev-side path. Also fixed an associative-array key check that wasn't portable to the macOS default bash 3.2. **Playwright audit script (subcommands: sidebar / darkmode / assets).** New `shared/scripts/site-audit.mjs` that opens each deployed subsite in a headless browser and: - `sidebar` — verifies every Quarto subsite has a visible sidebar (was missing on a few Vol I / Vol II combinations after the split). - `darkmode` — toggles dark mode, screenshots before/after, flags pages that don't repaint cleanly. - `assets` — fetches every `<img src>` and `<link rel="stylesheet">` and reports broken ones (catches the "PDF viewer iframe shows a 404" class of issue the maintainer flagged). Output goes to `.audit/` (added to `.gitignore` in PR-3). ### Risk surface - The announcement bar change is purely additive (new files; old file defanged but not deleted, so any forgotten reference still resolves). - The theme-persist script is `<head>`-inlined, so it runs before any user-visible content. Worst case if the script throws: nothing happens, the user falls back to OS preference (which is the current behavior). - The rewrite-dev-urls fix has been smoke-tested against vol1/vol2 paths and the depth math verified; included a comment in the script explaining the depth derivation. - The Playwright script is opt-in (run via `node shared/scripts/site-audit.mjs <cmd>`); no CI integration in this PR. ### Test plan - [ ] CI: book-validate-dev passes (announcement files parse as YAML). - [ ] Local: `node shared/scripts/site-audit.mjs sidebar` produces a JSON report covering vol1, vol2, tinytorch, labs, kits, slides, instructors, mlsysim, site, staffml. - [ ] Manual: dev mirror Vol II shows ETH-Blue announcement. - [ ] Manual: toggle dark mode on Vol I, navigate to TinyTorch, verify dark mode is preserved (no flash of light theme). ### Followup - Wire the audit script into a scheduled GitHub workflow (PR-3 has the dedup-finder follow-up; the audit script could share the same workflow shell). - Vol I announcement copy still reads "the unified Volume I/II edition is rolling out"; tighten language for actual launch. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

GiteaMirror added the pull-request label 2026-04-27 17:28:35 -05:00

GiteaMirror closed this issue

2026-04-27 17:28:36 -05:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/cs249r_book#8172