AGENTS.md

@@ -144,7 +144,9 @@ which helps to check what the server holds.
 - Keycloak sets `Secure` cookies; browsers send them to `http://localhost`, simple HTTP clients do not.
 - The login theme (`apps/keycloak/themes/mancala`) is CSS and one script on top of `keycloak.v2`. The script takes the
   theme from the `mancala_theme` cookie the web app writes (`saveThemeCookie`); the three themes' colors are copied
-  from `apps/frontend/src/styles/app.css`, so change both. Keycloak in `start` mode caches themes and keeps gzipped
+  from `apps/frontend/src/styles/app.css`, so change both. Browsers cache theme files under a path that only changes
+  with Keycloak's version, for an hour (`KC_SPI_THEME__STATIC_MAX_AGE` in the Dockerfile); after a change, check in a
+  private window or rename the file. Keycloak in `start` mode caches themes and keeps gzipped
   resources in `data/tmp/kc-gzip-cache` across restarts; see `apps/keycloak/README.md` for reloading it in a running
   container.
 

apps/keycloak/Dockerfile

@@ -19,5 +19,8 @@ COPY --from=builder /opt/keycloak/ /opt/keycloak/
 # Imported on startup only if the realm does not exist yet.
 COPY realm/mancala-realm.json /opt/keycloak/data/import/
 COPY themes/ /opt/keycloak/themes/
+# Browsers keep theme resources an hour instead of 30 days: their path only changes with Keycloak's version, so a
+# theme change would otherwise reach returning players a month late.
+ENV KC_SPI_THEME__STATIC_MAX_AGE=3600
 ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]
 CMD ["start", "--optimized", "--import-realm"]

apps/keycloak/README.md

@@ -38,7 +38,7 @@ console too, or delete the realm and restart Keycloak.
 `themes/mancala/login` gives the login, registration and password reset pages the web app's look in its three themes
 (Ceviz, Gece, Yeşim): its header, logo and name, font, cards, fields, pill buttons and a board with stones on top of
 the card (`docs/specs/theme-polish`). It extends Keycloak's `keycloak.v2` theme and only adds
-`resources/css/mancala.css` and `resources/js/theme.js`, so its templates and behaviour stay Keycloak's own and
+`resources/css/login.css` and `resources/js/theme.js`, so its templates and behaviour stay Keycloak's own and
 upgrades need no template changes.
 
 The script runs in the page's head and puts the theme's class (`t-ceviz`, `t-gece`, `t-yesim`) on `<html>`: the

apps/keycloak/themes/mancala/login/theme.properties

@@ -3,7 +3,9 @@
 parent=keycloak.v2
 import=common/keycloak
 
-styles=css/styles.css css/mancala.css
+# Browsers cache theme resources under a path that only changes with Keycloak's version: give a stylesheet a new name
+# when old copies must not be used (mancala.css was the grey theme's).
+styles=css/styles.css css/login.css
 # Picks the theme before the page is drawn; it also sets PatternFly's dark mode, so Keycloak's own is off.
 scripts=js/theme.js
 darkMode=false

docs/specs/theme-polish/design.md

@@ -17,10 +17,10 @@ See `requirements.md`; requirement ids (R1.1, …) are referenced below.
 
 ## Login theme (`apps/keycloak/themes/mancala/login`)
 
-- `theme.properties`: `darkMode=false`, `scripts=js/theme.js`, styles `css/styles.css css/mancala.css`.
+- `theme.properties`: `darkMode=false`, `scripts=js/theme.js`, styles `css/styles.css css/login.css`.
 - `js/theme.js`: reads `mancala_theme` (`ceviz`, `gece`, `yesim`), falls back to the color scheme, adds `t-<id>` and,
   for Ceviz and Gece, `pf-v5-theme-dark` to `<html>`.
-- `css/mancala.css`: the Bricolage Grotesque font; the tokens of `.t-ceviz`, `.t-gece`, `.t-yesim`; PatternFly's
+- `css/login.css`: the Bricolage Grotesque font; the tokens of `.t-ceviz`, `.t-gece`, `.t-yesim`; PatternFly's
   variables mapped to them; the header like the app's (logo, name), the card on `--surface`, inputs on `--surface2`,
   primary buttons in `--accent`, secondary ones outlined, links in `--ink`, errors in `--live`.
 - `img/logo-mask.svg`, `img/board-mask.svg`: alpha masks.