feat(pad): add theme-color meta to match toolbar on mobile (#7606)

[JohnMcLear]

Summary

Closes #7606.

Mobile browsers paint the address-bar / status-bar strip above the viewport using a system color when <meta name="theme-color"> is absent, leaving a visible gap above the Etherpad toolbar. This PR renders theme-color server-side so the bar blends into the configured toolbar from the first paint.

• New src/node/utils/SkinColors.ts resolves the colibris *-toolbar skin variants to the --bg-color values declared in colibris/src/pad-variants.css. Iteration order matches the CSS source so the last applicable token wins, mirroring the cascade.
• The helper returns null for non-colibris skins (no-skin, third-party skins) since their toolbar colors aren't known server-side; the templates then omit the meta rather than emit a misleading value.
• pad.html and timeslider.html emit a single unconditional <meta name="theme-color"> when the helper returns a color. No prefers-color-scheme media-query variants — the runtime dark-mode auto-switch in pad.ts is also gated on a localStorage white-mode override that a media query cannot express, so any media-query variant would risk painting a dark address bar over a still-light toolbar.
• Backend tests in specialpages.ts cover the rendered metas and the non-colibris skip path; vitest unit tests cover the helper.

Semver

patch — additive HTML metadata, no behavior change for existing clients.

Test plan

• Open a pad on a mobile device / Chromium devtools mobile emulator and confirm the address bar matches the toolbar.
• Configure skinVariants with dark-toolbar; confirm the address bar matches the dark toolbar.
• Configure skinName: "no-skin"; confirm the page renders with no theme-color meta.
• cd src && pnpm test -- tests/backend/specs/specialpages.ts
• cd src && pnpm test:vitest tests/backend-new/specs/SkinColors.ts

Generated with Claude Code

[qodo-code-review]

ⓘ You've reached your Qodo monthly free-tier limit. Reviews pause until next month — upgrade your plan to continue now, or link your paid account if you already have one.

[JohnMcLear]

/review

[qodo-code-review]

ⓘ You've reached your Qodo monthly free-tier limit. Reviews pause until next month — upgrade your plan to continue now, or link your paid account if you already have one.

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (1) 📎 Requirement gaps (0)

1. theme-color skipped for non-colibris ☑ 📎 Requirement gap ≡ Correctness

Description

pad.html only emits ` when configuredToolbarColor()` returns a value, but that helper returns
null for any skinName other than colibris. This means pads using no-skin or third-party
skins will not include the meta tag, failing the requirement that pad HTML output includes a
theme-color meta matching the active theme.

Code

src/templates/pad.html[51]

+  <% if (configuredColor) { %><meta name="theme-color" content="<%=configuredColor%>"><% } %>

Evidence

PR Compliance ID 1 requires pad HTML output to include a `` tag whose value matches the pad toolbar
color for the active theme. The new template emits the tag only if configuredColor is truthy, but
the new configuredToolbarColor() implementation returns null whenever skinName !== 'colibris',
so the meta tag is omitted for non-colibris themes.

Add <meta name="theme-color"> to pad HTML using toolbar color
src/templates/pad.html[9-14]
src/templates/pad.html[51-51]
src/node/utils/SkinColors.ts[23-33]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`pad.html` conditionally omits `<meta name="theme-color">` for non-colibris skins because `configuredToolbarColor()` returns `null` unless `skinName === 'colibris'`. This violates the requirement that pad HTML output includes a theme-color meta whose content matches the active theme's toolbar color.
## Issue Context
The current implementation avoids emitting a potentially wrong color for unknown skins, but the compliance requirement is explicit about always including the meta and matching the active theme.
## Fix Focus Areas
- src/templates/pad.html[9-14]
- src/templates/pad.html[51-51]
- src/node/utils/SkinColors.ts[23-33]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. theme-color wrong for no-skin ☑ 📎 Requirement gap ≡ Correctness

Description

pad.html always sets theme-color from settings.skinVariants via configuredToolbarColor(),
which is hardcoded to colibris variant colors and defaults to #ffffff. For the no-skin skin, the
actual toolbar background comes from core CSS (#f4f4f4), so the emitted theme-color will not
match the toolbar color for that theme.

Code

src/templates/pad.html[R51-52]

+  <meta name="theme-color" content="<%=configuredColor%>">
+  <% if (settings.enableDarkMode) { %><meta name="theme-color" content="<%=darkModeColor%>" media="(prefers-color-scheme: dark)"><% } %>

Evidence

Compliance ID 1 requires the theme-color meta to match the pad toolbar color for the active theme
(including non-default themes). The new meta tag uses
configuredToolbarColor(settings.skinVariants) (which falls back to #ffffff), but the core
toolbar background for the no-skin theme is #f4f4f4, so the meta color will not match the
toolbar in that configuration.

Add <meta name="theme-color"> to pad HTML matching the toolbar color
src/templates/pad.html[51-52]
src/node/utils/SkinColors.ts[14-31]
src/static/css/pad/toolbar.css[1-6]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`<meta name="theme-color">` is computed from colibris `skinVariants` and defaults to `#ffffff`, which does not match the toolbar color when `settings.skinName` is `no-skin` (core toolbar background is `#f4f4f4`). This violates the requirement that `theme-color` match the toolbar color for non-default themes.
## Issue Context
- `pad.html` emits `theme-color` based solely on `settings.skinVariants`.
- `SkinColors.configuredToolbarColor()` only knows colibris variant tokens and falls back to white.
- `no-skin` uses core CSS toolbar styling (`background-color: #f4f4f4`).
## Fix Focus Areas
- src/templates/pad.html[51-52]
- src/node/utils/SkinColors.ts[14-31]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. theme-color missing default meta ☑ 📎 Requirement gap ≡ Correctness

Description

The pad page emits the light theme-color only with media="(prefers-color-scheme: light)", and
omits the dark variant when settings.enableDarkMode is false. In a dark OS/browser color-scheme
this results in no applicable theme-color, so the browser UI will not match the (still light)
toolbar.

Code

src/templates/pad.html[R46-47]

+  <meta name="theme-color" content="<%=themeColors.light%>" media="(prefers-color-scheme: light)">
+  <% if (settings.enableDarkMode) { %><meta name="theme-color" content="<%=themeColors.dark%>" media="(prefers-color-scheme: dark)"><% } %>

Evidence

PR Compliance ID 2 requires the theme-color to match the toolbar color for the current pad theme;
however, the new light theme-color meta is conditional on prefers-color-scheme: light, and when
dark mode is disabled the code intentionally omits a dark meta tag—leaving no matching theme-color
in dark color-scheme environments.

Set theme-color to match toolbar color
src/templates/pad.html[46-47]
src/tests/backend/specs/specialpages.ts[81-89]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`pad.html` sets the light toolbar `theme-color` only for `(prefers-color-scheme: light)`. When `settings.enableDarkMode` is `false` and the user agent prefers dark, there is no applicable `theme-color`, causing the browser UI color to not match the (light) toolbar.
## Issue Context
The pad does not switch to dark variants unless `enableDarkMode` is enabled, so the toolbar remains light even if the OS/browser prefers dark.
## Fix Focus Areas
- src/templates/pad.html[46-47]
- src/tests/backend/specs/specialpages.ts[81-89]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View more (2)

4. Dark meta mismatches timeslider ☑ 🐞 Bug ≡ Correctness

Description

timeslider.html emits a prefers-color-scheme: dark theme-color meta whenever enableDarkMode is true,
but the timeslider client does not switch to dark skin-variant classes based on
prefers-color-scheme, so on dark-mode devices the browser chrome can be dark while the toolbar stays
in the configured (typically light) variant.

Code

src/templates/timeslider.html[R41-42]

+  <meta name="theme-color" content="<%=themeColors.light%>" media="(prefers-color-scheme: light)">
+  <% if (settings.enableDarkMode) { %><meta name="theme-color" content="<%=themeColors.dark%>" media="(prefers-color-scheme: dark)"><% } %>

Evidence

The timeslider template emits both light and dark theme-color metas (dark gated only by
enableDarkMode). The default configured skinVariants are light (super-light-toolbar), and colibris
CSS sets the toolbar background accordingly. The pad page has explicit JS to switch to dark variants
when prefers-color-scheme is dark, but the timeslider client initialization does not show comparable
logic, so the timeslider toolbar remains light even when the browser selects the dark theme-color
meta.

src/templates/timeslider.html[40-42]
src/node/utils/Settings.ts[333-344]
src/node/utils/SkinColors.ts[14-26]
src/static/js/pad.ts[648-652]
src/static/js/timeslider.ts[70-129]
src/static/skins/colibris/src/pad-variants.css[4-10]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`timeslider.html` emits a dark `theme-color` meta based on `prefers-color-scheme: dark` when `settings.enableDarkMode` is true, but the timeslider page does not appear to switch its toolbar to a dark variant based on OS color scheme. This can cause a persistent mismatch (dark address bar vs light toolbar) on dark-mode devices.
## Issue Context
Pad pages have client-side logic to switch to dark variants on dark OS preference; timeslider appears not to.
## Fix Focus Areas
- src/templates/timeslider.html[40-42]
- src/static/js/timeslider.ts[70-129]
- src/static/js/pad.ts[648-652]
### Implementation direction (choose one)
1) **Template-only mitigation**: Only emit a single `theme-color` meta for timeslider that matches the actual configured toolbar (no `prefers-color-scheme` variants), or only emit the dark variant if `settings.skinVariants` already includes a dark toolbar class.
2) **Proper dark-mode support for timeslider**: Add early client-side logic in `timeslider.ts` to mirror the pad page behavior (switch skin variant classes to the dark set when `enableDarkMode` and `matchMedia('(prefers-color-scheme: dark)')` match, respecting any stored user preference if applicable). Then the existing dark theme-color meta becomes accurate.
If you pick option (2), consider also updating the `theme-color` meta dynamically when the skin variants change so the browser chrome stays in sync.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. Dark meta mismatches timeslider ☑ 🐞 Bug ≡ Correctness

Description

timeslider.html emits a prefers-color-scheme: dark theme-color meta whenever enableDarkMode is true,
but the timeslider client does not switch to dark skin-variant classes based on
prefers-color-scheme, so on dark-mode devices the browser chrome can be dark while the toolbar stays
in the configured (typically light) variant.

Code

src/templates/timeslider.html[R41-42]

+  <meta name="theme-color" content="<%=themeColors.light%>" media="(prefers-color-scheme: light)">
+  <% if (settings.enableDarkMode) { %><meta name="theme-color" content="<%=themeColors.dark%>" media="(prefers-color-scheme: dark)"><% } %>

Evidence

The timeslider template emits both light and dark theme-color metas (dark gated only by
enableDarkMode). The default configured skinVariants are light (super-light-toolbar), and colibris
CSS sets the toolbar background accordingly. The pad page has explicit JS to switch to dark variants
when prefers-color-scheme is dark, but the timeslider client initialization does not show comparable
logic, so the timeslider toolbar remains light even when the browser selects the dark theme-color
meta.

src/templates/timeslider.html[40-42]
src/node/utils/Settings.ts[333-344]
src/node/utils/SkinColors.ts[14-26]
src/static/js/pad.ts[648-652]
src/static/js/timeslider.ts[70-129]
src/static/skins/colibris/src/pad-variants.css[4-10]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`timeslider.html` emits a dark `theme-color` meta based on `prefers-color-scheme: dark` when `settings.enableDarkMode` is true, but the timeslider page does not appear to switch its toolbar to a dark variant based on OS color scheme. This can cause a persistent mismatch (dark address bar vs light toolbar) on dark-mode devices.
## Issue Context
Pad pages have client-side logic to switch to dark variants on dark OS preference; timeslider appears not to.
## Fix Focus Areas
- src/templates/timeslider.html[40-42]
- src/static/js/timeslider.ts[70-129]
- src/static/js/pad.ts[648-652]
### Implementation direction (choose one)
1) **Template-only mitigation**: Only emit a single `theme-color` meta for timeslider that matches the actual configured toolbar (no `prefers-color-scheme` variants), or only emit the dark variant if `settings.skinVariants` already includes a dark toolbar class.
2) **Proper dark-mode support for timeslider**: Add early client-side logic in `timeslider.ts` to mirror the pad page behavior (switch skin variant classes to the dark set when `enableDarkMode` and `matchMedia('(prefers-color-scheme: dark)')` match, respecting any stored user preference if applicable). Then the existing dark theme-color meta becomes accurate.
If you pick option (2), consider also updating the `theme-color` meta dynamically when the skin variants change so the browser chrome stays in sync.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. Theme-color ignores white-mode 🐞 Bug ≡ Correctness

Description

On dark-OS clients, the server emits a dark prefers-color-scheme theme-color meta whenever
enableDarkMode is true, but the client explicitly avoids switching to dark toolbar classes if
localStorage has ep_darkMode='false' (white mode). This leaves the address bar/status bar dark while
the toolbar stays light, and there is no client-side logic to update the meta to the actual toolbar
color.

Code

src/templates/pad.html[R51-52]

+  <meta name="theme-color" content="<%=configuredColor%>">
+  <% if (settings.enableDarkMode) { %><meta name="theme-color" content="<%=darkModeColor%>" media="(prefers-color-scheme: dark)"><% } %>

Evidence

pad.html always renders a dark theme-color meta based on prefers-color-scheme when enableDarkMode is
enabled, but the client-side dark-mode auto-switch is gated on NOT having white-mode enabled in
localStorage, so the toolbar can remain light even while the dark meta applies. The skin variant
update paths shown do not update any theme-color meta after classes are changed/suppressed, so the
mismatch persists.

src/templates/pad.html[9-14]
src/templates/pad.html[51-52]
src/static/js/pad.ts[650-652]
src/static/js/skin_variants.ts[32-43]
src/static/js/pad_editor.ts[128-137]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`pad.html` emits a dark `theme-color` meta when `settings.enableDarkMode` is enabled, but the client can keep the UI in light mode on a dark OS (via `localStorage.ep_darkMode === 'false'`) or toggle modes after load. In those cases the browser chrome color (from the meta tag) can disagree with the actual toolbar background.
### Issue Context
Client code conditionally applies dark skin variants and supports a user override in localStorage; the server cannot know that override. To avoid a persistent mismatch, the `theme-color` meta should be updated client-side once the actual skin variant decision is known/applied.
### Fix Focus Areas
- src/templates/pad.html[51-52]
- src/static/js/pad.ts[650-656]
- src/static/js/pad_editor.ts[128-138]
- src/static/js/skin_variants.ts[8-24]
### Implementation sketch
- Add a small helper in client JS to set/update `<meta name="theme-color">` to the current toolbar background color (for example via `getComputedStyle(document.querySelector('.toolbar')).backgroundColor` and converting rgb->hex if needed, or by reading the relevant CSS variable).
- Call it after `skinVariants.updateSkinVariantsClasses(...)` and after the initial auto-switch decision (including the `isWhiteModeEnabledInLocalStorage()` case) so the meta always converges to the actually applied toolbar color.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

7. Dark color mismatches toolbar ☑ 🐞 Bug ≡ Correctness

Description

SkinColors.toolbarThemeColors() treats any configured token containing "dark" (e.g., "dark-toolbar")
as the dark-scheme theme-color, but the client-side dark mode code always switches the toolbar class
to "super-dark-toolbar". If settings.skinVariants includes "dark-toolbar", the server will emit
#576273 for dark theme-color while the actual toolbar in dark mode will be super-dark (#485365).

Code

src/node/utils/SkinColors.ts[R21-26]

+  for (const token of tokens) {
+    const color = TOOLBAR_COLORS[token];
+    if (!color) continue;
+    if (token.includes('dark')) dark = color;
+    else light = color;
+  }

Evidence

toolbarThemeColors() sets the returned dark value based on token names, so dark-toolbar
overrides DEFAULT_DARK. But the pad client forces the toolbar variant to super-dark-toolbar when
applying dark mode (both on initial load and when toggling), so the emitted dark theme-color should
match super-dark-toolbar, not dark-toolbar, for that mode.

src/node/utils/SkinColors.ts[7-28]
src/static/js/pad.ts[650-652]
src/static/js/pad_editor.ts[128-137]
src/static/skins/colibris/src/pad-variants.css[22-44]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`toolbarThemeColors()` can return `dark` = `#576273` when `settings.skinVariants` contains `dark-toolbar`, but the pad client applies `super-dark-toolbar` for dark mode, so the server-rendered dark `theme-color` can disagree with the real toolbar color.
### Issue Context
Both initial dark-mode application and the UI toggle hardcode `super-dark-toolbar`.
### Fix Focus Areas
- src/node/utils/SkinColors.ts[17-28]
- src/templates/pad.html[42-48]
### Suggested change
Make the pad page’s dark-scheme theme-color match the toolbar class that is actually used in dark mode (`super-dark-toolbar`). Options include:
- Adjust `toolbarThemeColors()` (or introduce a pad-specific helper) so `dark` is derived from `TOOLBAR_COLORS['super-dark-toolbar']` instead of being overridden by `dark-toolbar`.
- Update tests accordingly (the expected dark theme-color should match the forced `super-dark-toolbar` behavior).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

8. theme-color lacks feature flag ☑ 📘 Rule violation ⚙ Maintainability

Description

The PR introduces a new always-on code path that emits `` without any feature flag or
disable-by-default mechanism. This violates the requirement that new features be gated so they can
be safely toggled off if needed.

Code

src/templates/pad.html[R46-47]

+  <meta name="theme-color" content="<%=themeColors.light%>" media="(prefers-color-scheme: light)">
+  <% if (settings.enableDarkMode) { %><meta name="theme-color" content="<%=themeColors.dark%>" media="(prefers-color-scheme: dark)"><% } %>

Evidence

PR Compliance ID 5 requires new features to be implemented behind a feature flag and disabled by
default. The added HTML meta tags are rendered unconditionally for the light scheme (and
conditionally for dark mode), with no new flag or config to disable the behavior.

src/templates/pad.html[46-47]
src/templates/timeslider.html[41-42]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`<meta name="theme-color">` emission is a new behavior that is enabled unconditionally (for light mode) and is not protected by a feature flag that is disabled by default.
## Issue Context
Compliance requires new features to be opt-in/flagged so they can be turned off safely if needed.
## Fix Focus Areas
- src/templates/pad.html[46-47]
- src/templates/timeslider.html[41-42]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View more (3)

9. Light theme-color stays white ☑ 🐞 Bug ≡ Correctness

Description

If settings.skinVariants contains only a dark toolbar variant (for example "dark-toolbar"),
toolbarThemeColors() updates only the returned "dark" color and leaves "light" at the white default,
so the emitted light-scheme <meta name="theme-color"> won't match the actual dark toolbar on
light-mode devices.

Code

src/node/utils/SkinColors.ts[R17-26]

+export const toolbarThemeColors = (skinVariants: string | undefined | null) => {
+  const tokens = (skinVariants || '').split(/\s+/).filter(Boolean);
+  let light = DEFAULT_LIGHT;
+  let dark = DEFAULT_DARK;
+  for (const token of tokens) {
+    const color = TOOLBAR_COLORS[token];
+    if (!color) continue;
+    if (token.includes('dark')) dark = color;
+    else light = color;
+  }

Evidence

toolbarThemeColors() initializes light to #ffffff and only updates it for non-"dark" tokens, so a
dark-only toolbar token never updates the light value. The templates always emit a light-scheme
theme-color meta using themeColors.light, but the colibris CSS sets a dark toolbar background for
the dark-toolbar class, so the address/status bar color will not match the rendered toolbar in light
OS color scheme.

src/node/utils/SkinColors.ts[17-27]
src/templates/pad.html[45-47]
src/static/skins/colibris/src/pad-variants.css[36-44]
src/static/skins/colibris/pad.css[33-42]
src/node/utils/Settings.ts[333-344]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`toolbarThemeColors()` leaves `light` at `#ffffff` when the configured `settings.skinVariants` contains only a dark toolbar variant (e.g. `dark-toolbar`). This causes the emitted `prefers-color-scheme: light` theme-color meta to be white even though the toolbar background is dark.
## Issue Context
This shows up when an instance is configured with a dark toolbar variant but the user's OS/browser is in light mode.
## Fix Focus Areas
- src/node/utils/SkinColors.ts[17-27]
### Implementation direction
Adjust `toolbarThemeColors()` so that a toolbar variant token sets the effective toolbar color for both schemes unless an explicit scheme-specific override is present. For example:
- Track the last matched `*-toolbar` token color as `toolbar`.
- Initialize `{light, dark}` to `{toolbar, toolbar}` when `toolbar` is found.
- If you want separate values, only split when both a light-toolbar and dark-toolbar token are present.
Also add/extend unit tests to cover a `skinVariants` string that contains only `dark-toolbar` and assert that `.light` is set to `#576273` (or whatever the configured toolbar color is).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

10. theme-color lacks feature flag 📘 Rule violation ⚙ Maintainability

Description

The PR introduces a new always-on code path that emits `` without any feature flag or
disable-by-default mechanism. This violates the requirement that new features be gated so they can
be safely toggled off if needed.

Code

src/templates/pad.html[R46-47]

+  <meta name="theme-color" content="<%=themeColors.light%>" media="(prefers-color-scheme: light)">
+  <% if (settings.enableDarkMode) { %><meta name="theme-color" content="<%=themeColors.dark%>" media="(prefers-color-scheme: dark)"><% } %>

Evidence

PR Compliance ID 5 requires new features to be implemented behind a feature flag and disabled by
default. The added HTML meta tags are rendered unconditionally for the light scheme (and
conditionally for dark mode), with no new flag or config to disable the behavior.

src/templates/pad.html[46-47]
src/templates/timeslider.html[41-42]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`<meta name="theme-color">` emission is a new behavior that is enabled unconditionally (for light mode) and is not protected by a feature flag that is disabled by default.
## Issue Context
Compliance requires new features to be opt-in/flagged so they can be turned off safely if needed.
## Fix Focus Areas
- src/templates/pad.html[46-47]
- src/templates/timeslider.html[41-42]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

11. Light theme-color stays white ☑ 🐞 Bug ≡ Correctness

Description

If settings.skinVariants contains only a dark toolbar variant (for example "dark-toolbar"),
toolbarThemeColors() updates only the returned "dark" color and leaves "light" at the white default,
so the emitted light-scheme <meta name="theme-color"> won't match the actual dark toolbar on
light-mode devices.

Code

src/node/utils/SkinColors.ts[R17-26]

+export const toolbarThemeColors = (skinVariants: string | undefined | null) => {
+  const tokens = (skinVariants || '').split(/\s+/).filter(Boolean);
+  let light = DEFAULT_LIGHT;
+  let dark = DEFAULT_DARK;
+  for (const token of tokens) {
+    const color = TOOLBAR_COLORS[token];
+    if (!color) continue;
+    if (token.includes('dark')) dark = color;
+    else light = color;
+  }

Evidence

toolbarThemeColors() initializes light to #ffffff and only updates it for non-"dark" tokens, so a
dark-only toolbar token never updates the light value. The templates always emit a light-scheme
theme-color meta using themeColors.light, but the colibris CSS sets a dark toolbar background for
the dark-toolbar class, so the address/status bar color will not match the rendered toolbar in light
OS color scheme.

src/node/utils/SkinColors.ts[17-27]
src/templates/pad.html[45-47]
src/static/skins/colibris/src/pad-variants.css[36-44]
src/static/skins/colibris/pad.css[33-42]
src/node/utils/Settings.ts[333-344]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`toolbarThemeColors()` leaves `light` at `#ffffff` when the configured `settings.skinVariants` contains only a dark toolbar variant (e.g. `dark-toolbar`). This causes the emitted `prefers-color-scheme: light` theme-color meta to be white even though the toolbar background is dark.
## Issue Context
This shows up when an instance is configured with a dark toolbar variant but the user's OS/browser is in light mode.
## Fix Focus Areas
- src/node/utils/SkinColors.ts[17-27]
### Implementation direction
Adjust `toolbarThemeColors()` so that a toolbar variant token sets the effective toolbar color for both schemes unless an explicit scheme-specific override is present. For example:
- Track the last matched `*-toolbar` token color as `toolbar`.
- Initialize `{light, dark}` to `{toolbar, toolbar}` when `toolbar` is found.
- If you want separate values, only split when both a light-toolbar and dark-toolbar token are present.
Also add/extend unit tests to cover a `skinVariants` string that contains only `dark-toolbar` and assert that `.light` is set to `#576273` (or whatever the configured toolbar color is).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

12. Mixed export styles ☑ 🐞 Bug ⚙ Maintainability

Description

SkinColors.ts uses both TypeScript named exports and a CommonJS module.exports assignment, which is
redundant and makes module semantics harder to reason about across require() and TS imports. This
increases the risk of accidental breakage when refactoring or changing build tooling.

Code

src/node/utils/SkinColors.ts[R17-43]

+export const toolbarThemeColors = (skinVariants: string | undefined | null) => {
+  const tokens = (skinVariants || '').split(/\s+/).filter(Boolean);
+  let light = DEFAULT_LIGHT;
+  let dark = DEFAULT_DARK;
+  for (const token of tokens) {
+    const color = TOOLBAR_COLORS[token];
+    if (!color) continue;
+    if (token.includes('dark')) dark = color;
+    else light = color;
+  }
+  return {light, dark};
+};
+
+// The toolbar color that the configured skinVariants resolves to with no
+// client-side dark-mode toggling. Used by pages (e.g. timeslider) that do not
+// switch skin variants based on prefers-color-scheme, so that theme-color
+// always matches what the user actually sees.
+export const configuredToolbarColor = (skinVariants: string | undefined | null) => {
+  const tokens = (skinVariants || '').split(/\s+/).filter(Boolean);
+  for (const token of tokens) {
+    const color = TOOLBAR_COLORS[token];
+    if (color) return color;
+  }
+  return DEFAULT_LIGHT;
+};
+
+module.exports = {toolbarThemeColors, configuredToolbarColor};

Evidence

The file defines export const ... and then overwrites exports via module.exports = ....
Elsewhere in the repo, TS utilities generally stick to one module style per file (either ES exports
or CommonJS).

src/node/utils/SkinColors.ts[17-43]
src/templates/pad.html[1-9]
src/tests/backend-new/specs/SkinColors.ts[1-2]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`src/node/utils/SkinColors.ts` mixes ES exports (`export const ...`) with CommonJS (`module.exports = ...`). This is redundant and can create confusion or subtle interop issues over time.
### Issue Context
- EJS templates load the helper via `require('.../SkinColors')`.
- Vitest tests import it via `import { ... } from ...`.
- TS is configured for `module: CommonJS`, so ES named exports already compile to CommonJS-compatible exports.
### Fix Focus Areas
- src/node/utils/SkinColors.ts[17-43]
### Suggested fix
- Remove `module.exports = ...` and rely on the existing `export const ...` named exports (TypeScript will emit CommonJS exports under the current tsconfig).
- Alternatively, remove the `export` keywords and switch callers/tests to `require()` consistently, but prefer the first option for TS files.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

13. Toolbar token precedence wrong 🐞 Bug ≡ Correctness

Description

configuredToolbarColor() returns the first matching toolbar token in settings.skinVariants, but if
multiple toolbar variants are present the actual toolbar color is determined by CSS cascade order,
not token order. This can cause timeslider’s theme-color to disagree with the rendered toolbar.

Code

src/node/utils/SkinColors.ts[R34-39]

+export const configuredToolbarColor = (skinVariants: string | undefined | null) => {
+  const tokens = (skinVariants || '').split(/\s+/).filter(Boolean);
+  for (const token of tokens) {
+    const color = TOOLBAR_COLORS[token];
+    if (color) return color;
+  }

Evidence

configuredToolbarColor() exits on the first match, but the colibris CSS defines multiple toolbar
variant rules; if more than one toolbar class is present, the later rule in the stylesheet wins,
which can differ from the first token in the class string.

src/node/utils/SkinColors.ts[34-41]
src/static/skins/colibris/src/pad-variants.css[4-44]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`configuredToolbarColor()` returns the first toolbar token it finds, which can diverge from the color that actually applies if `settings.skinVariants` includes multiple `*-toolbar` classes.
### Issue Context
CSS cascade (stylesheet order) decides which `--bg-color` wins when multiple toolbar classes exist.
### Fix Focus Areas
- src/node/utils/SkinColors.ts[34-41]
### Suggested change
Prefer the last matching toolbar token in `skinVariants` (or explicitly enforce/validate that only one toolbar variant is allowed) so the computed theme-color better matches what the CSS will render.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-free-for-open-source-projects]

Review Summary by Qodo

Add theme-color meta tags matching toolbar on mobile

✨ Enhancement

Walkthroughs

Description

• Add server-side theme-color meta tags matching toolbar colors
• Create SkinColors utility mapping skin variants to toolbar colors
• Support light and dark theme variants with prefers-color-scheme media queries
• Add comprehensive unit and integration tests for theme-color rendering

Diagram

flowchart LR
  A["SkinColors.ts<br/>Toolbar color mapping"] --> B["pad.html<br/>Render theme-color meta"]
  A --> C["timeslider.html<br/>Render theme-color meta"]
  B --> D["Mobile browser<br/>Matching address bar"]
  C --> D
  E["settings.skinVariants<br/>settings.enableDarkMode"] --> A

Loading

File Changes

1. src/node/utils/SkinColors.ts ✨ Enhancement +30/-0

Toolbar color mapping utility

• New utility module mapping colibris skin variant tokens to toolbar background colors
• Exports toolbarThemeColors() function that parses skinVariants and returns light/dark color
 objects
• Mirrors --bg-color values from pad-variants.css for server-side color resolution
• Provides sensible defaults (white for light, dark gray for dark)

src/node/utils/SkinColors.ts

---

2. src/tests/backend-new/specs/SkinColors.ts 🧪 Tests +42/-0

Unit tests for SkinColors utility

• New vitest unit test suite for SkinColors.toolbarThemeColors function
• Tests default color handling for empty/null/undefined inputs
• Tests individual toolbar variant mappings (super-light, light, dark, super-dark)
• Tests mixed variant handling and ignoring unrelated tokens

src/tests/backend-new/specs/SkinColors.ts

---

3. src/tests/backend/specs/specialpages.ts 🧪 Tests +55/-0

Integration tests for theme-color meta tags

• Add integration test suite for theme-color meta tag rendering
• Test light and dark theme-color variants with prefers-color-scheme media queries
• Test dark mode disabled scenario (omits dark variant)
• Test explicit dark toolbar variant selection
• Test theme-color rendering on both pad and timeslider pages

src/tests/backend/specs/specialpages.ts

---

View more (2)

4. src/templates/pad.html ✨ Enhancement +4/-0

Add theme-color meta tags to pad template

• Import SkinColors utility module
• Call toolbarThemeColors() with settings.skinVariants to get light/dark colors
• Render light theme-color meta tag with prefers-color-scheme: light media query
• Conditionally render dark theme-color meta tag when enableDarkMode is true

src/templates/pad.html

---

5. src/templates/timeslider.html ✨ Enhancement +4/-0

Add theme-color meta tags to timeslider template

• Import SkinColors utility module
• Call toolbarThemeColors() with settings.skinVariants to get light/dark colors
• Render light theme-color meta tag with prefers-color-scheme: light media query
• Conditionally render dark theme-color meta tag when enableDarkMode is true

src/templates/timeslider.html

---

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (1) 📎 Requirement gaps (0)

Context used

✅ Tickets: 🎫 Add <meta name="theme-color"> html to pads.

1. Dark meta mismatches timeslider 🐞 Bug ≡ Correctness

Description

timeslider.html emits a prefers-color-scheme: dark theme-color meta whenever enableDarkMode is true,
but the timeslider client does not switch to dark skin-variant classes based on
prefers-color-scheme, so on dark-mode devices the browser chrome can be dark while the toolbar stays
in the configured (typically light) variant.

Code

src/templates/timeslider.html[R41-42]

+  <meta name="theme-color" content="<%=themeColors.light%>" media="(prefers-color-scheme: light)">
+  <% if (settings.enableDarkMode) { %><meta name="theme-color" content="<%=themeColors.dark%>" media="(prefers-color-scheme: dark)"><% } %>

Evidence

The timeslider template emits both light and dark theme-color metas (dark gated only by
enableDarkMode). The default configured skinVariants are light (super-light-toolbar), and colibris
CSS sets the toolbar background accordingly. The pad page has explicit JS to switch to dark variants
when prefers-color-scheme is dark, but the timeslider client initialization does not show comparable
logic, so the timeslider toolbar remains light even when the browser selects the dark theme-color
meta.

src/templates/timeslider.html[40-42]
src/node/utils/Settings.ts[333-344]
src/node/utils/SkinColors.ts[14-26]
src/static/js/pad.ts[648-652]
src/static/js/timeslider.ts[70-129]
src/static/skins/colibris/src/pad-variants.css[4-10]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`timeslider.html` emits a dark `theme-color` meta based on `prefers-color-scheme: dark` when `settings.enableDarkMode` is true, but the timeslider page does not appear to switch its toolbar to a dark variant based on OS color scheme. This can cause a persistent mismatch (dark address bar vs light toolbar) on dark-mode devices.

## Issue Context
Pad pages have client-side logic to switch to dark variants on dark OS preference; timeslider appears not to.

## Fix Focus Areas
- src/templates/timeslider.html[40-42]
- src/static/js/timeslider.ts[70-129]
- src/static/js/pad.ts[648-652]

### Implementation direction (choose one)
1) **Template-only mitigation**: Only emit a single `theme-color` meta for timeslider that matches the actual configured toolbar (no `prefers-color-scheme` variants), or only emit the dark variant if `settings.skinVariants` already includes a dark toolbar class.

2) **Proper dark-mode support for timeslider**: Add early client-side logic in `timeslider.ts` to mirror the pad page behavior (switch skin variant classes to the dark set when `enableDarkMode` and `matchMedia('(prefers-color-scheme: dark)')` match, respecting any stored user preference if applicable). Then the existing dark theme-color meta becomes accurate.

If you pick option (2), consider also updating the `theme-color` meta dynamically when the skin variants change so the browser chrome stays in sync.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. theme-color lacks feature flag 📘 Rule violation ⚙ Maintainability

Description

The PR introduces a new always-on code path that emits <meta name="theme-color"> without any
feature flag or disable-by-default mechanism. This violates the requirement that new features be
gated so they can be safely toggled off if needed.

Code

src/templates/pad.html[R46-47]

+  <meta name="theme-color" content="<%=themeColors.light%>" media="(prefers-color-scheme: light)">
+  <% if (settings.enableDarkMode) { %><meta name="theme-color" content="<%=themeColors.dark%>" media="(prefers-color-scheme: dark)"><% } %>

Evidence

PR Compliance ID 5 requires new features to be implemented behind a feature flag and disabled by
default. The added HTML meta tags are rendered unconditionally for the light scheme (and
conditionally for dark mode), with no new flag or config to disable the behavior.

src/templates/pad.html[46-47]
src/templates/timeslider.html[41-42]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`<meta name="theme-color">` emission is a new behavior that is enabled unconditionally (for light mode) and is not protected by a feature flag that is disabled by default.

## Issue Context
Compliance requires new features to be opt-in/flagged so they can be turned off safely if needed.

## Fix Focus Areas
- src/templates/pad.html[46-47]
- src/templates/timeslider.html[41-42]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Light theme-color stays white 🐞 Bug ≡ Correctness

Description

If settings.skinVariants contains only a dark toolbar variant (for example "dark-toolbar"),
toolbarThemeColors() updates only the returned "dark" color and leaves "light" at the white default,
so the emitted light-scheme <meta name="theme-color"> won't match the actual dark toolbar on
light-mode devices.

Code

src/node/utils/SkinColors.ts[R17-26]

+export const toolbarThemeColors = (skinVariants: string | undefined | null) => {
+  const tokens = (skinVariants || '').split(/\s+/).filter(Boolean);
+  let light = DEFAULT_LIGHT;
+  let dark = DEFAULT_DARK;
+  for (const token of tokens) {
+    const color = TOOLBAR_COLORS[token];
+    if (!color) continue;
+    if (token.includes('dark')) dark = color;
+    else light = color;
+  }

Evidence

toolbarThemeColors() initializes light to #ffffff and only updates it for non-"dark" tokens, so a
dark-only toolbar token never updates the light value. The templates always emit a light-scheme
theme-color meta using themeColors.light, but the colibris CSS sets a dark toolbar background for
the dark-toolbar class, so the address/status bar color will not match the rendered toolbar in light
OS color scheme.

src/node/utils/SkinColors.ts[17-27]
src/templates/pad.html[45-47]
src/static/skins/colibris/src/pad-variants.css[36-44]
src/static/skins/colibris/pad.css[33-42]
src/node/utils/Settings.ts[333-344]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`toolbarThemeColors()` leaves `light` at `#ffffff` when the configured `settings.skinVariants` contains only a dark toolbar variant (e.g. `dark-toolbar`). This causes the emitted `prefers-color-scheme: light` theme-color meta to be white even though the toolbar background is dark.

## Issue Context
This shows up when an instance is configured with a dark toolbar variant but the user's OS/browser is in light mode.

## Fix Focus Areas
- src/node/utils/SkinColors.ts[17-27]

### Implementation direction
Adjust `toolbarThemeColors()` so that a toolbar variant token sets the effective toolbar color for both schemes unless an explicit scheme-specific override is present. For example:
- Track the last matched `*-toolbar` token color as `toolbar`.
- Initialize `{light, dark}` to `{toolbar, toolbar}` when `toolbar` is found.
- If you want separate values, only split when both a light-toolbar and dark-toolbar token are present.

Also add/extend unit tests to cover a `skinVariants` string that contains only `dark-toolbar` and assert that `.light` is set to `#576273` (or whatever the configured toolbar color is).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[JohnMcLear]

/review

[qodo-code-review]

ⓘ You've reached your Qodo monthly free-tier limit. Reviews pause until next month — upgrade your plan to continue now, or link your paid account if you already have one.

[qodo-free-for-open-source-projects]

Persistent review updated to latest commit 7b41829

[JohnMcLear]

/review

[qodo-code-review]

ⓘ You've reached your Qodo monthly free-tier limit. Reviews pause until next month — upgrade your plan to continue now, or link your paid account if you already have one.

[qodo-free-for-open-source-projects]

Persistent review updated to latest commit dcedf72

[JohnMcLear]

/review

[qodo-code-review]

ⓘ You've reached your Qodo monthly free-tier limit. Reviews pause until next month — upgrade your plan to continue now, or link your paid account if you already have one.

[qodo-free-for-open-source-projects]

Persistent review updated to latest commit d6753cc

[JohnMcLear]

On Qodo finding #4 ("theme-color lacks feature flag"): leaving this as-is and not gating it.

<meta name="theme-color"> is additive HTML metadata that fixes a mobile UX bug (#7606) where the browser address bar painted a system color above the toolbar. It's not a behavior change for any client, has no runtime cost, and falls back gracefully on browsers that ignore it. Adding a config flag would just add a setting nobody needs to toggle.

[JohnMcLear]

/review

[qodo-code-review]

ⓘ You've reached your Qodo monthly free-tier limit. Reviews pause until next month — upgrade your plan to continue now, or link your paid account if you already have one.

[qodo-free-for-open-source-projects]

Persistent review updated to latest commit 51115af