dev-centr · AMDphreak · Aug 12, 2026 · Aug 12, 2026
diff --git a/README.adoc b/README.adoc
@@ -50,7 +50,7 @@ This repository contains the Antora playbook and configuration for the **Dev Cen
 | `antora-playbook.yml` | Production Antora playbook. Uses remote GitHub URLs for all content sources and the published UI bundle. Used by CI/CD.
 | `antora-playbook-local.yml` | Local sibling-repo playbook (committed). Expects content repos as siblings (see the playbook `sources` list: `../devcentr`, `../switchyard`, `../msi-generator`, …).
 | `antora-playbook.testing.yml` | Same local content sources, but points `ui.bundle` at `../valentus-theme/build/ui-bundle.zip` for theme work.
-| `supplemental-ui/` | Site overlay on the valentus-theme 2.x UI bundle: custom domain `CNAME`, accent-token brand CSS, header logo under `img/`, and a thin `head-meta.hbs` fork that loads the brand stylesheet. Header logo / navbar text use playbook `site.keys`.
+| `supplemental-ui/` | Site overlay on the valentus-theme 2.x UI bundle: custom domain `CNAME`, accent-token brand CSS, header logo under `img/`, and a thin `head-meta.hbs` fork (FOUC paint-hold + preference boot scripts vendored from Valentus, plus the brand stylesheet link). Header logo / navbar text use playbook `site.keys`.
 | `.vscode/` | VS Code folder settings and extension recommendations for this playbook repo.
 | `package.json` | Defines dependencies and build scripts.
 |===

diff --git a/dark-mode-analysis.md b/dark-mode-analysis.md
@@ -10,6 +10,6 @@ Migrated from the retired `antora-dark-theme` package (2026-06).
 
 As of valentus-theme 2.x, header logo and navbar branding use playbook `site.keys` (for example `header_logo`) plus optional SVGs in `supplemental-ui/img/`. Search lives in the tool band (not the header). Consumers should not override `partials/header-content.hbs` for logo wiring alone; keep `head-meta.hbs` in sync with upstream when upgrading.
 
-Color theming uses `supplemental-ui/css/devcentr-brand.css` (accent-token overrides), loaded from a thin `head-meta.hbs` fork (vendored from valentus so FOUC / dark-mode / read-width boot stay intact). Playbook `site.keys` stay snake_case; Antora camelCases them for the UI model.
+Color theming uses `supplemental-ui/css/devcentr-brand.css` (accent-token overrides), loaded from a thin `head-meta.hbs` fork (vendored from valentus so FOUC paint-hold, dark-mode, read-width, and font-size boot stay intact). The interim `adt-fouc-pending` class hides the page until layered CSS and preference attrs apply; keep brand CSS in the stylesheet stack before the release script. Playbook `site.keys` stay snake_case; Antora camelCases them for the UI model.
 
 See `docs/modules/ROOT/pages/publishing/antora-ui-branding.adoc`.
diff --git a/docs/modules/ROOT/pages/activity-log.adoc b/docs/modules/ROOT/pages/activity-log.adoc
@@ -8,6 +8,7 @@ This page records significant documentation and project activity at an org level
 
 === August
 
+* **valentus-theme FOUC paint-hold** — Synced supplemental `head-meta.hbs` with Valentus interim paint-hold (`adt-fouc-pending`): hide until layered CSS and preference attrs apply, then release after read-width/font-size boot. Brand CSS stays in the stylesheet stack before the release script. xref:publishing/antora-ui-branding.adoc#fouc-paint-hold-interim[Antora UI branding].
 * **AsciiDoc image alts + SVG encoding** — Unquoted `image::file.svg[A, B]` became HTML `width="B"`; opening some SVGs also hit XML *Encoding error* (non-UTF-8 / bare `&`). Quoted alts and rewrote Access/GCP SVGs as UTF-8 XML. xref:general-knowledge::how-to/cloudflare-access-static-site.adoc[Access how-to].
 * **Access Finish setup + multi-org consent** — Cloudflare dashboard first, GitHub unlocked in the same browser; Authorize listing other orgs does not widen Access. xref:general-knowledge::how-to/cloudflare-access-static-site.adoc#finish-github-setup[Finish setup] · xref:general-knowledge::how-to/cloudflare-access-static-site.adoc#github-consent-other-orgs[Other orgs] · xref:tools/cloudflare-access.adoc[portal].
 * **Language recommendations** — Small-set suggestions (D, Rust, TypeScript, Julia, Lisp/Haskell) plus reconstructed C/D, C++/D, Julia/D/Java, and D/Rust comparisons (dead Gemini shares). xref:general-knowledge::explanation/languages/index.adoc[Recommendations].

diff --git a/docs/modules/ROOT/pages/publishing/antora-ui-branding.adoc b/docs/modules/ROOT/pages/publishing/antora-ui-branding.adoc
@@ -37,6 +37,21 @@ Do **not** override `partials/header-content.hbs` unless you need markup the the
 
 When upgrading valentus-theme, re-diff `head-meta.hbs` against upstream and keep the brand CSS link after `site-visual.css` / `site-read-width.css` / `site-font-size.css`. The font-size FOUC script and stylesheet are required for the condensed A/A/A control (desktop hide + doc zoom).
 
+== FOUC paint-hold (interim)
+
+Valentus 2.x ships an interim *paint-hold* in `head-meta.hbs` while Default UI single-pass CSS lands (see link:https://gitlab.com/antora/antora-ui-default/-/merge_requests/207[antora-ui-default!207] and upstream FOUC/stylesheets guidance). The supplemental overlay must stay in sync with that block.
+
+Load order in `supplemental-ui/partials/head-meta.hbs`:
+
+. Inline `html.adt-fouc-pending { visibility: hidden !important; }` plus a script that adds `adt-fouc-pending` on `<html>` *before* stylesheets.
+. All layered CSS links (fonts, `site-doc-layout.css`, `site-visual.css`, read-width, font-size, `devcentr-brand.css`, mermaid, math).
+. Preference boot scripts (dark mode, read-width, font-size) that set `data-*` attrs / `dark-theme` from `localStorage`.
+. A final script that removes `adt-fouc-pending` *after* those scripts run.
+
+Do **not** place the paint-hold release script before the brand or module stylesheets — users would see a flash of unstyled or wrong-accent chrome. Do **not** drop the read-width or font-size FOUC blocks; they are separate from the global paint-hold but must run before the release script.
+
+When valentus-theme updates this partial, copy the upstream paint-hold comment block and release timing, then re-insert the `devcentr-brand.css` link in the stylesheet stack.
+
 == Header logo and navbar text
 
 [source,yaml]

diff --git a/supplemental-ui/partials/head-meta.hbs b/supplemental-ui/partials/head-meta.hbs
@@ -1,5 +1,28 @@
+{{!--
+  HACK (interim paint-hold): hide until layered CSS + preference attrs apply.
+  Copied from Valentus head-meta — pending upstream Default UI single-pass CSS
+  (antora-ui-default!207 + master FOUC/stylesheets guidance). Keep brand CSS
+  links with the other stylesheets, before the paint-hold release script.
+--}}
+<style>
+html.adt-fouc-pending { visibility: hidden !important; }
+</style>
+<script>
+document.documentElement.classList.add('adt-fouc-pending')
+</script>
 <link rel="stylesheet" href="{{{uiRootPath}}}/css/site-extra.css">
 <meta name="dm-navbar" content="{{or site.keys.darkModeNavbar 'light'}}">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600&family=Plus+Jakarta+Sans:ital,wght@0,500;0,600;0,700;1,500&family=Source+Sans+3:ital,wght@0,400;0,500;0,600;0,700;1,400&display=swap">
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-doc-layout.css">
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-visual.css">
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-read-width.css">
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-font-size.css">
+{{!-- DevCentr brand token overlay (after valentus visual CSS) --}}
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/devcentr-brand.css">
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-mermaid.css">
+<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-math.css">
 <script>
 (function () {
   const dmNavbar = document.querySelector('meta[name="dm-navbar"]')
@@ -52,17 +75,9 @@
   }
 })()
 </script>
-<link rel="preconnect" href="https://fonts.googleapis.com">
-<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600&family=Plus+Jakarta+Sans:ital,wght@0,500;0,600;0,700;1,500&family=Source+Sans+3:ital,wght@0,400;0,500;0,600;0,700;1,400&display=swap">
-<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-doc-layout.css">
-<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-visual.css">
-<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-read-width.css">
-<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-font-size.css">
-{{!-- DevCentr brand token overlay (after valentus visual CSS) --}}
-<link rel="stylesheet" href="{{{uiRootPath}}}/css/devcentr-brand.css">
-<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-mermaid.css">
-<link rel="stylesheet" href="{{{uiRootPath}}}/css/site-math.css">
+<script>
+document.documentElement.classList.remove('adt-fouc-pending')
+</script>
 {{#if page.origin.webUrl}}
 <meta name="antora-repo-url" content="{{page.origin.webUrl}}">
 {{/if}}