sbpp
diff --git a/‎.github/workflows/docs-screenshots-capture.yml‎
Lines changed: 29 additions & 2 deletions b/‎.github/workflows/docs-screenshots-capture.yml‎
Lines changed: 29 additions & 2 deletions
diff --git a/‎docs/README.md‎
Lines changed: 26 additions & 0 deletions b/‎docs/README.md‎
Lines changed: 26 additions & 0 deletions
diff --git a/‎docs/scripts/capture.mjs‎
Lines changed: 137 additions & 21 deletions b/‎docs/scripts/capture.mjs‎
Lines changed: 137 additions & 21 deletions
@@ -1,6 +1,23 @@
 # docs-screenshots-capture — boot the dev stack, capture installer +
 # panel screenshots, and commit the diff back to the PR branch.
 #
+# Capture geometry (driven by docs/scripts/capture.mjs):
+#
+#   - Viewport: 1920×1080 (Full HD), with `fullPage: true` so the
+#     entire scrollable surface lands in the PNG.
+#   - Panel routes are captured TWICE — once in light mode and once
+#     in dark — and emit per-theme PNGs (e.g.
+#     `panel-02-dashboard-light.png`, `panel-02-dashboard-dark.png`).
+#     The dark pass seeds `localStorage['sbpp-theme']` via Playwright's
+#     `addInitScript` so the inline FOUC bootloader in
+#     `core/header.tpl` lands `<html class="dark">` on the first
+#     paint (no white flash). See AGENTS.md "Anti-FOUC theme
+#     bootloader" for the contract.
+#   - Install routes are captured ONCE in the :root light default.
+#     The wizard's `_chrome.tpl` doesn't load `theme.js` or the FOUC
+#     bootloader (the wizard has no theme toggle by design; see
+#     AGENTS.md "Install wizard").
+#
 # SECURITY MODEL — read this before changing the workflow.
 #
 # `pull_request_target` runs with the upstream repo's GITHUB_TOKEN
@@ -212,7 +229,13 @@ jobs:
       # below moves the file aside on the host (the bind-mounted
       # `./web` means the container sees the rename immediately) for
       # the duration of the install captures, then restores it.
-      - name: Capture panel screenshots
+      #
+      # The panel pass loops both `light` and `dark` themes inside
+      # `capture.mjs` (one browser context per theme; localStorage
+      # seeded before navigation so the FOUC bootloader picks dark
+      # up on the first paint). See the workflow header comment
+      # for the per-theme output naming.
+      - name: Capture panel screenshots (light + dark, 1920×1080 full-page)
         working-directory: trusted/docs
         env:
           STEAM_API_KEY: '00000000000000000000000000000000'
@@ -231,7 +254,11 @@ jobs:
             echo "web/config.php was already absent; nothing to stash"
           fi
 
-      - name: Capture install screenshots
+      # Install pass is light-only — the wizard's `_chrome.tpl`
+      # doesn't load `theme.js` or the FOUC bootloader, so a "dark
+      # install" capture would just be the same light render with a
+      # different filename (see the workflow header comment).
+      - name: Capture install screenshots (light only, 1920×1080 full-page)
         working-directory: trusted/docs
         env:
           STEAM_API_KEY: '00000000000000000000000000000000'
 
@@ -72,6 +72,32 @@ The script writes PNGs into `src/assets/auto/install/` and
 what changed; commit the deltas alongside the UI change that produced
 them.
 
+Capture geometry:
+
+- **Viewport: 1920×1080 (Full HD), full-page screenshots.** The
+  rendered PNG carries the full scrollable surface so high-DPI /
+  zoomed-in inspection works without re-running the capture. The
+  docs site renders the PNGs at responsive widths.
+- **Panel routes are captured TWICE — once light, once dark.**
+  Each route emits a `<route>-light.png` and a `<route>-dark.png`
+  (e.g. `panel-02-dashboard-light.png` /
+  `panel-02-dashboard-dark.png`). The dark pass seeds
+  `localStorage['sbpp-theme']` before navigation so the inline FOUC
+  bootloader in `core/header.tpl` lands the `dark` class on
+  `<html>` on the first paint (no white flash). See AGENTS.md
+  "Anti-FOUC theme bootloader" for the contract.
+- **Install routes are captured ONCE in light.** The wizard's
+  `_chrome.tpl` doesn't load `theme.js` or the FOUC bootloader (the
+  wizard has no theme toggle by design — see AGENTS.md "Install
+  wizard"); a "dark install" capture would just be the same light
+  render with a different filename.
+- **The output subdirectory is wiped at the start of each run.**
+  `CAPTURE_ROUTES=panel` clears `src/assets/auto/panel/` before
+  capturing, `=install` clears `src/assets/auto/install/`, and the
+  default `=all` clears both. Stale PNGs from earlier runs (route
+  list changes, pre-dual-theme legacy filenames) don't linger in
+  the committed diff.
+
 The hardcoded `STEAM_API_KEY` is `00000000000000000000000000000000`
 (an all-zero dummy) — the dev seed never round-trips back to Steam,
 so the zero key is safe and avoids leaking real keys into screenshots.
 
@@ -54,14 +54,37 @@
 //                       Requires `web/config.php` to be absent so
 //                       the C2 guard doesn't intercept.
 //
+// Output shape:
+//   - Panel routes are captured TWICE — once with the panel's light
+//     theme active and once with dark — and emit per-theme PNGs
+//     (`panel-02-dashboard-light.png`, `panel-02-dashboard-dark.png`,
+//     etc.). The dark variant seeds `localStorage['sbpp-theme']`
+//     before the page paints so the inline FOUC bootloader in
+//     `core/header.tpl` lands the `dark` class on `<html>` on the
+//     very first frame (no white flash). The browser context's
+//     `colorScheme` is matched to the panel theme so native UA
+//     surfaces (scrollbars, native pickers, autofill highlighting)
+//     paint in the matching scheme too — see theme.css's
+//     `color-scheme` declarations (#1309).
+//   - Install routes are captured ONCE in the :root light default.
+//     The wizard's `_chrome.tpl` doesn't load `theme.js` or the
+//     FOUC bootloader (the wizard has no theme toggle by design;
+//     see AGENTS.md "Install wizard"), so a "dark install" capture
+//     would just be the same light render with a different filename.
+//
+// Default capture geometry is 1920×1080 viewport with `fullPage: true`
+// so the entire scrollable surface lands in the PNG (the docs site
+// renders these at responsive widths, but the source PNG carries the
+// full layout for high-DPI / zoomed-in inspection).
+//
 // The script is intentionally a runnable SKELETON for the first PR.
 // The route list below is the bones; flesh out per-route selectors
 // + click sequences as the install / panel chrome iterates. Routes
 // with `TODO:` notes are deferred to follow-up PRs that exercise
 // the actual flow end-to-end.
 
 import { chromium } from '@playwright/test';
-import { mkdir } from 'node:fs/promises';
+import { mkdir, rm } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -83,10 +106,26 @@ const STEAM_API_KEY =
   process.env.STEAM_API_KEY ?? '00000000000000000000000000000000';
 const ADMIN_USER = process.env.PANEL_ADMIN_USER ?? 'admin';
 const ADMIN_PASS = process.env.PANEL_ADMIN_PASS ?? 'admin';
-// Crop window chrome to a consistent viewport so screenshots line up
+// Pin the viewport to Full HD (1920×1080) so screenshots line up
 // across runs even when the runner's chromium gets a different
-// default size.
-const VIEWPORT = { width: 1280, height: 800 };
+// default size. Combined with `fullPage: true` on the screenshot
+// call, the rendered PNG carries the full scrollable surface at
+// the largest viewport the panel chrome's responsive breakpoints
+// target — wide enough to surface tier-3 desktop-table columns
+// (see AGENTS.md "Responsive desktop-table chrome") and the full
+// sidebar + content shell on the admin routes.
+const VIEWPORT = { width: 1920, height: 1080 };
+
+// Panel themes to capture. Each panel route runs once per theme in
+// its own browser context; the dark pass seeds
+// `localStorage['sbpp-theme']` via `addInitScript` so the FOUC
+// bootloader in `core/header.tpl` resolves to dark BEFORE the
+// document body parses (the bootloader is the synchronous read; see
+// AGENTS.md "Anti-FOUC theme bootloader" for the contract). The
+// install wizard chrome doesn't carry the bootloader, so install
+// routes are captured light-only — see `main()` below.
+/** @type {readonly ('light' | 'dark')[]} */
+const PANEL_THEMES = ['light', 'dark'];
 
 // CAPTURE_ROUTES picks which route groups run. CI invokes us twice
 // (once per group) with config.php stashed around the install pass
@@ -179,9 +218,23 @@ const INSTALL_ROUTES = [
   },
 ];
 
+// Reset the output directories for the route groups we're about to
+// capture so a previous run's stale PNGs (e.g. last-run filenames
+// that don't match the current route list, or pre-dual-theme legacy
+// `panel-02-dashboard.png` from before per-theme suffixes landed)
+// don't linger in the committed diff. We only nuke the subdir for
+// the group actually being captured so a `CAPTURE_ROUTES=panel`
+// invocation doesn't wipe a previous `install` capture (or vice
+// versa). `force: true` makes the missing-directory case idempotent.
 async function ensureOutDirs() {
-  await mkdir(OUT_INSTALL, { recursive: true });
-  await mkdir(OUT_PANEL, { recursive: true });
+  if (CAPTURE_ROUTES === 'all' || CAPTURE_ROUTES === 'install') {
+    await rm(OUT_INSTALL, { recursive: true, force: true });
+    await mkdir(OUT_INSTALL, { recursive: true });
+  }
+  if (CAPTURE_ROUTES === 'all' || CAPTURE_ROUTES === 'panel') {
+    await rm(OUT_PANEL, { recursive: true, force: true });
+    await mkdir(OUT_PANEL, { recursive: true });
+  }
 }
 
 /**
@@ -215,10 +268,46 @@ async function loginAsAdmin(page) {
  * @param {import('@playwright/test').Browser} browser
  * @param {CaptureRoute[]} routes
  * @param {string} outDir
- * @param {{ login?: boolean }} [opts]
+ * @param {{ login?: boolean; theme?: 'light' | 'dark' }} [opts]
  */
 async function captureRoutes(browser, routes, outDir, opts = {}) {
-  const ctx = await browser.newContext({ viewport: VIEWPORT });
+  /** @type {import('@playwright/test').BrowserContextOptions} */
+  const contextOptions = { viewport: VIEWPORT };
+  if (opts.theme) {
+    // Pair the OS-level scheme with the panel-side theme so native
+    // UA surfaces (scrollbars, native pickers, autofill highlighting)
+    // paint in the matching scheme too — mirrors the `color-scheme`
+    // declarations on `:root` / `html.dark` in theme.css (#1309).
+    // The bootloader is the load-bearing path for the panel chrome
+    // itself; this is belt-and-suspenders for the surfaces the
+    // browser draws on top of our DOM.
+    contextOptions.colorScheme = opts.theme;
+  }
+  const ctx = await browser.newContext(contextOptions);
+
+  if (opts.theme) {
+    // Seed `localStorage['sbpp-theme']` BEFORE any page navigation
+    // so the inline FOUC bootloader in `core/header.tpl` (which runs
+    // synchronously in `<head>` BEFORE `<body>` parses, ABOVE the
+    // stylesheet link) reads the value and sets `<html class="dark">`
+    // on the very first paint. Without the seed, the panel would
+    // start in :root light defaults and theme.js (loaded from the
+    // document tail via `core/footer.tpl`) would flip the class
+    // mid-paint, producing the white-flash regression #1367 fixed.
+    // Playwright's `addInitScript` runs after the document is
+    // created but before any of its own scripts execute, which is
+    // exactly the slot we need.
+    await ctx.addInitScript((target) => {
+      try {
+        localStorage.setItem('sbpp-theme', target);
+      } catch (_err) {
+        // Private-mode SecurityError; the bootloader's own try/catch
+        // falls through to the :root light default in that case,
+        // matching theme.js's defensiveness.
+      }
+    }, opts.theme);
+  }
+
   const page = await ctx.newPage();
 
   if (opts.login) {
@@ -235,7 +324,11 @@ async function captureRoutes(browser, routes, outDir, opts = {}) {
     const url = route.url.startsWith('http')
       ? route.url
       : `${PANEL_URL}${route.url}`;
-    const target = join(outDir, `${route.name}.png`);
+    // Per-theme suffix on the filename so the light + dark variants
+    // co-exist in the same output directory. Install routes pass no
+    // theme and keep the bare slug.
+    const slug = opts.theme ? `${route.name}-${opts.theme}` : route.name;
+    const target = join(outDir, `${slug}.png`);
 
     try {
       await page.goto(url, { waitUntil: 'networkidle', timeout: 15_000 });
@@ -244,7 +337,11 @@ async function captureRoutes(browser, routes, outDir, opts = {}) {
       }
       await page.screenshot({
         path: target,
-        fullPage: route.fullPage ?? false,
+        // Default to `fullPage: true` so the whole scrollable
+        // surface lands in the PNG; routes can still opt out
+        // explicitly via `fullPage: false` in their config (e.g.
+        // a chrome-only shot of the login form).
+        fullPage: route.fullPage ?? true,
       });
       const note = route.todo ? `  (TODO: ${route.todo})` : '';
       console.log(`[capture] wrote ${target}${note}`);
@@ -262,6 +359,8 @@ async function main() {
   console.log(`[capture] PANEL_URL=${PANEL_URL}`);
   console.log(`[capture] STEAM_API_KEY=${STEAM_API_KEY}`);
   console.log(`[capture] CAPTURE_ROUTES=${CAPTURE_ROUTES}`);
+  console.log(`[capture] VIEWPORT=${VIEWPORT.width}x${VIEWPORT.height}`);
+  console.log(`[capture] PANEL_THEMES=${PANEL_THEMES.join(',')}`);
   console.log(
     `[capture] writing → ${OUT_INSTALL} (install) and ${OUT_PANEL} (panel)`,
   );
@@ -273,20 +372,37 @@ async function main() {
       // `web/config.php` is absent — see the header comment for
       // the C2-guard rationale. CI stashes the file around this
       // call; local-dev defaults render the 409 page.
+      //
+      // The install chrome (`_chrome.tpl`) doesn't load `theme.js`
+      // or the FOUC bootloader (the wizard has no theme toggle by
+      // design — see AGENTS.md "Install wizard"). Capture once in
+      // the :root light default with no per-theme suffix; trying
+      // to flip the wizard to dark would just produce the same
+      // light render under a different filename.
       await captureRoutes(browser, INSTALL_ROUTES, OUT_INSTALL);
     }
     if (CAPTURE_ROUTES === 'all' || CAPTURE_ROUTES === 'panel') {
-      // Anonymous pass — captures the login screen before any
-      // session cookie exists. Splitting this from the auth pass
-      // avoids the `<script>window.location.href='index.php'</script>`
-      // post-login redirect aborting the goto.
-      await captureRoutes(browser, PANEL_PUBLIC_ROUTES, OUT_PANEL);
-      // Authenticated pass — fresh context, drives the login form,
-      // then visits the admin-only routes so they paint actual
-      // content instead of the login wall.
-      await captureRoutes(browser, PANEL_AUTH_ROUTES, OUT_PANEL, {
-        login: true,
-      });
+      // Panel routes capture both light and dark variants. Each
+      // theme runs in its own browser context so the localStorage
+      // seeding is clean and the cookie/login state is rebuilt
+      // per pass (logging in twice costs ~200ms total — cheap).
+      for (const theme of PANEL_THEMES) {
+        // Anonymous pass — captures the login screen before any
+        // session cookie exists. Splitting this from the auth
+        // pass avoids the
+        // `<script>window.location.href='index.php'</script>`
+        // post-login redirect aborting the goto.
+        await captureRoutes(browser, PANEL_PUBLIC_ROUTES, OUT_PANEL, {
+          theme,
+        });
+        // Authenticated pass — fresh context, drives the login
+        // form, then visits the admin-only routes so they paint
+        // actual content instead of the login wall.
+        await captureRoutes(browser, PANEL_AUTH_ROUTES, OUT_PANEL, {
+          login: true,
+          theme,
+        });
+      }
     }
   } finally {
     await browser.close();