Theme CSS Loading — Step 4: Implementation Summary

Stage 1 - Define theme asset and hint contracts

• Changes:

  • Added the canonical theme-hint cookie name, explicit-theme validation, and per-theme stylesheet paths to ThemeRegistry.

  • Added registry coverage for the cookie, valid theme paths, and rejection of auto or unknown hints.

• Verification:

  • php -l src/ForumRewrite/View/ThemeRegistry.php

  • php -l tests/ThemeRegistryTest.php

  • php tests/run.php ThemeRegistryTest — 5 tests passed.

• Notes:

  • Cookie reading and rendering are intentionally deferred to Stages 3–4.

Stage 2 - Extract shared and per-theme stylesheets

• Changes:

  • Reduced site.css from 94,509 to 40,753 bytes by retaining shared, fallback, and critical rules only.

  • Extracted all 13 explicit theme selector groups, including their responsive rules and swatch styling, to fingerprintable theme-<name>.css assets.

  • Added a regression test that requires every registered theme asset and rejects explicit theme selectors in the shared stylesheet.

• Verification:

  • php tests/run.php ThemeRegistryTest — 6 tests passed.

  • Confirmed all 13 stylesheet assets are non-empty and no direct explicit-theme, swatch, or theme-option selector remains in site.css.

• Notes:

  • The unscoped light variables remain in site.css as the deliberate no-JavaScript/default fallback.

Stage 3 - Render the prioritized stylesheet link

• Changes:

  • Added a validated theme-hint lookup to the shared renderer and a fingerprinted stylesheet manifest for every explicit theme.

  • Rendered one high-priority theme stylesheet link before the head resolver; a valid hint (or explicit site default) supplies its initial path.

  • Extended the early resolver to replace a stale or missing hinted path with the client-resolved explicit or Auto/System theme before first paint.

• Verification:

  • php tests/run.php LocalAppSmokeTest::testLayoutUsesOnlyAValidatedThemeHintForTheInitialStylesheet LocalAppSmokeTest::testCompactModeMenuStylesUseScopedDensitySelectors LocalAppSmokeTest::testApplicationRendersCoreRoutes ThemeRegistryTest — passed.

  • Confirmed valid word97 and invalid auto hints respectively render the fingerprinted Word 97 and fallback Light stylesheet paths.

• Notes:

  • The hint is not trusted as user preference and auto is rejected server-side.

Stage 4 - Reconcile preference, Auto/System, and hint updates

• Changes:

  • The early resolver now writes the cookie only when its resolved concrete theme differs from the current hint.

  • The theme script keeps the active stylesheet, resolved-theme attribute, and cookie hint synchronized after explicit selections and Auto/System scheme changes.

  • Kept the stored auto/explicit preference separate from the concrete cookie value.

• Verification:

  • php -l src/ForumRewrite/View/TemplateRenderer.php

  • node -c public/assets/theme_toggle.js

  • php tests/run.php LocalAppSmokeTest::testLayoutUsesOnlyAValidatedThemeHintForTheInitialStylesheet ThemeRegistryTest — passed.

• Notes:

  • Cookie lifetime is one year, path is site-wide, and Secure is added on HTTPS.

Stage 5 - Warm alternate themes and preserve responsive switching

• Changes:

  • Added idle-time, low-priority loading for every non-active resolved theme stylesheet.

  • Added stylesheet readiness tracking; a selection promotes an unfinished asset and waits without switching to incomplete styling.

  • Preserved immediate application for already warm/cached themes and kept Auto/System changes synchronized while their asset warms.

• Verification:

  • node -c public/assets/theme_toggle.js

  • php tests/run.php LocalAppSmokeTest::testThemeToggleWarmsAlternateThemeStylesheetsAtLowPriority LocalAppSmokeTest::testLayoutUsesOnlyAValidatedThemeHintForTheInitialStylesheet ThemeRegistryTest — passed.

• Notes:

  • A failed stylesheet request releases the loading state so controls cannot become permanently stuck.

Stage 6 - Cover static artifacts and regressions

• Changes:

  • Added static-artifact coverage that requires every fingerprinted theme stylesheet to be referenced by the generated layout and present in its artifact assets.

  • Reused the existing asset copier and fingerprint reference health check; no release-pipeline change was needed.

  • Updated the Word 97 invitation regression to read its extracted theme stylesheet.

• Verification:

  • php tests/run.php LocalAppSmokeTest::testStaticArtifactBuilderWritesApacheFriendlyArtifactLayout LocalAppSmokeTest::testLayoutUsesOnlyAValidatedThemeHintForTheInitialStylesheet LocalAppSmokeTest::testThemeToggleWarmsAlternateThemeStylesheetsAtLowPriority ThemeRegistryTest — passed.

  • php tests/run.php InvitationIssuanceTest — passed after moving its Word 97 assertion to the extracted asset.

  • Full php tests/run.php run: theme-related coverage passed; unrelated failures remain in activity-manifest, adjacent-signature, and lazy-compose test paths.

• Notes:

  • Static pages use the default hint-free initial link; pages carrying a theme hint already take the dynamic path and are corrected by the early resolver.

Final Verification

• Changes:

  • None; recorded final route-level verification.

• Verification:

  • Started php -S 127.0.0.1:8099 -t public public/router.php, requested /, and confirmed the fingerprinted Light theme link plus all 13 fingerprinted theme paths in the rendered manifest.

• Notes:

  • Stopped the temporary development server after the check.