From 0ca0c7cf434b404b4b4c350c9a13c3ea647dae88 Mon Sep 17 00:00:00 2001
From: StroepWafel <contact@stroepwafel.au>
Date: Mon, 20 Apr 2026 21:43:05 +0930
Subject: [PATCH 01/10] add handlers for individual Channels

---
 .gitignore                                    |  3 +-
 src/seqta/ui/colors/Manager.ts                | 37 ++++++++++-
 .../ui/colors/customThemeAdaptiveBindings.ts  | 64 ++++++++++++++-----
 3 files changed, 85 insertions(+), 19 deletions(-)

diff --git a/.gitignore b/.gitignore
index e24ea199..46e7ae3b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,4 +22,5 @@ betterseqtaplus-safari/
 .parcel-cache
 .env
 .env.submit
-dependency-graph.svg
\ No newline at end of file
+dependency-graph.svg
+/src/resources/themes
diff --git a/src/seqta/ui/colors/Manager.ts b/src/seqta/ui/colors/Manager.ts
index d72c8844..2adccfbf 100644
--- a/src/seqta/ui/colors/Manager.ts
+++ b/src/seqta/ui/colors/Manager.ts
@@ -5,7 +5,7 @@ import { lightenAndPaleColor } from "./lightenAndPaleColor";
 import ColorLuminance from "./ColorLuminance";
 import { settingsState } from "@/seqta/utils/listeners/SettingsState";
 import { getAdaptiveColour } from "@/seqta/utils/adaptiveThemeColour";
-import { getCustomThemeAdaptiveCssVariables } from "@/seqta/ui/colors/customThemeAdaptiveBindings";
+import { getCustomThemeAdaptiveCssVariableBindings } from "@/seqta/ui/colors/customThemeAdaptiveBindings";
 
 import darkLogo from "@/resources/icons/betterseqta-light-full.png";
 import lightLogo from "@/resources/icons/betterseqta-dark-full.png";
@@ -84,6 +84,21 @@ function cancelColorTransition() {
   }
 }
 
+function getRepresentativeRgbChannels(s: string): { r: number; g: number; b: number } | null {
+  const parsedHex = parseRepresentativeHex(s);
+  if (!parsedHex) return null;
+  try {
+    const [r, g, b] = Color(parsedHex).rgb().array();
+    return {
+      r: Math.round(r),
+      g: Math.round(g),
+      b: Math.round(b),
+    };
+  } catch {
+    return null;
+  }
+}
+
 function applyColorsWith(selectedColor: string) {
   if (settingsState.transparencyEffects) {
     document.documentElement.classList.add("transparencyEffects");
@@ -129,8 +144,24 @@ function applyColorsWith(selectedColor: string) {
   applyProperties({ ...commonProps, ...modeProps, ...dynamicProps });
 
   if (settingsState.selectedTheme) {
-    for (const name of getCustomThemeAdaptiveCssVariables()) {
-      setCSSVar(name, selectedColor);
+    const channels = getRepresentativeRgbChannels(selectedColor);
+    for (const binding of getCustomThemeAdaptiveCssVariableBindings()) {
+      if (!binding.channel) {
+        setCSSVar(binding.cssVarName, selectedColor);
+        continue;
+      }
+
+      if (!channels) {
+        continue;
+      }
+
+      if (binding.channel === "r") {
+        setCSSVar(binding.cssVarName, String(channels.r));
+      } else if (binding.channel === "g") {
+        setCSSVar(binding.cssVarName, String(channels.g));
+      } else {
+        setCSSVar(binding.cssVarName, String(channels.b));
+      }
     }
   }
 
diff --git a/src/seqta/ui/colors/customThemeAdaptiveBindings.ts b/src/seqta/ui/colors/customThemeAdaptiveBindings.ts
index dba35e3f..cdd0c823 100644
--- a/src/seqta/ui/colors/customThemeAdaptiveBindings.ts
+++ b/src/seqta/ui/colors/customThemeAdaptiveBindings.ts
@@ -1,20 +1,49 @@
 /** Tracks which author-declared CSS variables mirror the effective accent; not persisted in settings storage. */
 
 const VALID_CUSTOM_PROP = /^--[a-zA-Z0-9_-]{1,120}$/;
+const VALID_CHANNEL = /^(r|g|b)$/;
 
-let boundNames: string[] = [];
+export type AdaptiveChannel = "r" | "g" | "b";
 
-export function normalizeAdaptiveCssVariableNames(
+export type AdaptiveCssVariableBinding = {
+  cssVarName: string;
+  channel?: AdaptiveChannel;
+};
+
+let boundBindings: AdaptiveCssVariableBinding[] = [];
+
+function parseAdaptiveBinding(
+  rawBinding: string,
+): AdaptiveCssVariableBinding | null {
+  const trimmed = rawBinding.trim();
+  if (!trimmed) return null;
+
+  const [rawName, rawChannel] = trimmed.split(":", 2);
+  const cssVarName = rawName?.trim() ?? "";
+  if (!VALID_CUSTOM_PROP.test(cssVarName)) return null;
+
+  if (!rawChannel) return { cssVarName };
+
+  const channel = rawChannel.trim().toLowerCase();
+  if (!VALID_CHANNEL.test(channel)) return null;
+
+  return { cssVarName, channel: channel as AdaptiveChannel };
+}
+
+export function normalizeAdaptiveCssVariableBindings(
   names: string[] | undefined,
-): string[] {
+): AdaptiveCssVariableBinding[] {
   if (!names?.length) return [];
-  const out: string[] = [];
+  const out: AdaptiveCssVariableBinding[] = [];
   const seen = new Set<string>();
+
   for (const raw of names) {
-    const s = raw.trim();
-    if (!VALID_CUSTOM_PROP.test(s) || seen.has(s)) continue;
-    seen.add(s);
-    out.push(s);
+    const parsed = parseAdaptiveBinding(raw);
+    if (!parsed) continue;
+    const key = `${parsed.cssVarName}:${parsed.channel ?? "full"}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(parsed);
   }
   return out;
 }
@@ -22,19 +51,24 @@ export function normalizeAdaptiveCssVariableNames(
 export function setCustomThemeAdaptiveCssVariables(
   names: string[] | undefined,
 ): void {
-  for (const n of boundNames) {
-    document.documentElement.style.removeProperty(n);
+  for (const binding of boundBindings) {
+    document.documentElement.style.removeProperty(binding.cssVarName);
   }
-  boundNames = normalizeAdaptiveCssVariableNames(names);
+  boundBindings = normalizeAdaptiveCssVariableBindings(names);
 }
 
+export function getCustomThemeAdaptiveCssVariableBindings(): AdaptiveCssVariableBinding[] {
+  return boundBindings;
+}
+
+// Backward-compatible helper for existing callsites.
 export function getCustomThemeAdaptiveCssVariables(): string[] {
-  return boundNames;
+  return boundBindings.map((b) => b.cssVarName);
 }
 
 export function clearCustomThemeAdaptiveCssVariables(): void {
-  for (const n of boundNames) {
-    document.documentElement.style.removeProperty(n);
+  for (const binding of boundBindings) {
+    document.documentElement.style.removeProperty(binding.cssVarName);
   }
-  boundNames = [];
+  boundBindings = [];
 }

From 37be31859f4ab37b8bbaff5c51f95c47192d0f34 Mon Sep 17 00:00:00 2001
From: StroepWafel <contact@stroepwafel.au>
Date: Mon, 20 Apr 2026 21:47:05 +0930
Subject: [PATCH 02/10] add notes

---
 src/seqta/utils/Openers/OpenWhatsNewPopup.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/seqta/utils/Openers/OpenWhatsNewPopup.ts b/src/seqta/utils/Openers/OpenWhatsNewPopup.ts
index bbe7f386..06e44fa9 100644
--- a/src/seqta/utils/Openers/OpenWhatsNewPopup.ts
+++ b/src/seqta/utils/Openers/OpenWhatsNewPopup.ts
@@ -34,6 +34,9 @@ export function OpenWhatsNewPopup(onDismissed?: () => void) {
   const text = stringToHTML(/* html */ `
     <div class="whatsnewTextContainer" style="height: 50%;overflow-y: auto;">
 
+      <h1>3.6.3 - Adaptive theme channel bindings & Alpine refresh</h1>
+      <li>Added adaptive CSS variable channel bindings for custom themes: use <code>--my-var:r</code>, <code>--my-var:g</code>, or <code>--my-var:b</code> in <code>adaptiveCssVariables</code>.</li>
+      <li>Adaptive theme bindings now support both full-colour and single-channel values, enabling more reliable theme math without fragile CSS colour parsing.</li>
       <h1>3.6.2 - Cloud backup, various fixes & SEQTA Engage support</h1>
       <li>BetterSEQTA Cloud: back up and restore extension settings from your account (General settings).</li>
       <li>Optional automatic cloud sync if signed in (on by default).</li>

From 44116edca50f0d0e48409898bb13596d27df823c Mon Sep 17 00:00:00 2001
From: StroepWafel <contact@stroepwafel.au>
Date: Mon, 20 Apr 2026 22:50:39 +0930
Subject: [PATCH 03/10] patch fix theme overrides for adaptive colour

---
 src/css/injected.scss          |  5 +++--
 src/seqta/ui/colors/Manager.ts | 11 +++++++++++
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/src/css/injected.scss b/src/css/injected.scss
index 261552c2..9c5fe51c 100644
--- a/src/css/injected.scss
+++ b/src/css/injected.scss
@@ -1,3 +1,4 @@
+
 @use "sass:meta";
 @import url("https://fonts.googleapis.com/css?family=Rubik:300,400,500,600,700");
 
@@ -2609,7 +2610,7 @@ body {
 
 [class*="MessageList__unread___"] {
   position: relative;
-  background: rgb(228 225 225);
+  background: var(--background-secondary, rgb(228 225 225));
 }
 
 .dark [class*="MessageList__unread___"] {
@@ -2735,7 +2736,7 @@ body {
 [class*="MessageList__MessageList___"]
   > ol
   > li[class*="MessageList__selected___"] {
-  background: rgb(228 225 225);
+  background: var(--background-secondary, rgb(228 225 225));
   color: var(--text-primary);
   box-shadow: none !important;
   position: relative;
diff --git a/src/seqta/ui/colors/Manager.ts b/src/seqta/ui/colors/Manager.ts
index 2adccfbf..71740da9 100644
--- a/src/seqta/ui/colors/Manager.ts
+++ b/src/seqta/ui/colors/Manager.ts
@@ -165,6 +165,17 @@ function applyColorsWith(selectedColor: string) {
     }
   }
 
+  // Let themes opt-in to overriding only adaptive accent output.
+  // A theme can define `--adaptive-better-main` from adaptive channel bindings.
+  if (settingsState.selectedTheme && settingsState.adaptiveThemeColour) {
+    const adaptiveOverride = getComputedStyle(document.documentElement)
+      .getPropertyValue("--adaptive-better-main")
+      .trim();
+    if (adaptiveOverride) {
+      setCSSVar("--better-main", adaptiveOverride);
+    }
+  }
+
   let alliframes = document.getElementsByTagName("iframe");
 
   for (let i = 0; i < alliframes.length; i++) {

From fa8f36f3d5fcd5bad706ee16b8cfd14247dd6bbf Mon Sep 17 00:00:00 2001
From: StroepWafel <contact@stroepwafel.au>
Date: Tue, 21 Apr 2026 20:31:06 +0930
Subject: [PATCH 04/10] idk

---
 .cursor/skills/theme-authoring/SKILL.md      | 96 ++++++++++++++++++++
 src/plugins/built-in/themes/theme-manager.ts |  4 +-
 2 files changed, 99 insertions(+), 1 deletion(-)
 create mode 100644 .cursor/skills/theme-authoring/SKILL.md

diff --git a/.cursor/skills/theme-authoring/SKILL.md b/.cursor/skills/theme-authoring/SKILL.md
new file mode 100644
index 00000000..58de7286
--- /dev/null
+++ b/.cursor/skills/theme-authoring/SKILL.md
@@ -0,0 +1,96 @@
+---
+name: theme-authoring
+description: Creates BetterSEQTA+ custom themes as `.theme.json` files for import or publishing to the BetterSEQTA theme store. Use when the user asks to make a new theme, adjust theme colors/CSS, or prepare a theme JSON for upload.
+---
+
+# Theme authoring (BetterSEQTA+)
+
+## Goal
+Produce a valid `*.theme.json` file that BetterSEQTA+ can install (via theme import or store download).
+
+## Output contract
+Return:
+- The final theme JSON (ready to save as `my-theme.theme.json`)
+- A short list of the main palette values used (accent + background + text)
+
+## Theme JSON schema (practical)
+Required keys:
+- `id`: string (stable identifier; use kebab-case, e.g. `banana-theme`)
+- `name`: string (display name)
+- `description`: string
+- `defaultColour`: string CSS color (e.g. `rgb(...)` or `#RRGGBB`)
+- `CanChangeColour`: boolean
+- `CustomCSS`: string (CSS applied as a `<style>` tag)
+
+Common optional keys:
+- `hideThemeName`: boolean
+- `forceTheme`: boolean (when true, the theme forces light/dark)
+- `forceDark`: boolean (when forcing, `true` = dark, `false` = light)
+- `images`: array of `{ id, variableName, data }` where `data` is base64 PNG (no prefix required, but allowed)
+- `coverImage`: base64 image string (optional)
+- `adaptiveCssVariables`: string[] (advanced; see below)
+
+## Workflow
+### 1) Pick a theme concept + palette
+Decide:
+- **Accent**: set as `defaultColour`
+- **Surfaces**: `--background-primary`, `--background-secondary`
+- **Text**: set `--theme-fg-parts` to a readable RGB triple
+
+If the theme is intended to be “bright” and friendly, default to **forced light**:
+- `forceTheme: true`, `forceDark: false`
+
+If it’s intended to be “night/dark”, default to **forced dark**:
+- `forceTheme: true`, `forceDark: true`
+
+### 2) Write `CustomCSS`
+Use a consistent, minimal set of overrides:
+- In `:root` set:
+  - `--background-primary`, `--background-secondary`
+  - `--theme-offset-bg`, `--theme-offset-bg-more` (slightly darker/lighter than secondary)
+  - `--theme-bg-parts`, `--theme-sel-bg-parts`, `--theme-fg-parts` (RGB triples)
+- Set the page background on:
+  - `html, body, #container, #content`
+  - Use 2–3 subtle `radial-gradient(...)` layers + a `linear-gradient(...)`
+  - Finish with `, var(--background) !important;` so custom backgrounds still work
+
+Recommended template (edit values and gradient stops):
+
+```json
+{
+  "id": "my-theme",
+  "name": "My Theme",
+  "description": "One-line vibe description.",
+  "defaultColour": "rgb(123, 100, 200)",
+  "CanChangeColour": true,
+  "hideThemeName": false,
+  "forceTheme": true,
+  "forceDark": false,
+  "CustomCSS": ":root {\\n  --background-primary: rgb(255, 255, 255) !important;\\n  --background-secondary: rgb(235, 235, 235) !important;\\n  --theme-offset-bg: rgb(245, 245, 245) !important;\\n  --theme-offset-bg-more: rgb(225, 225, 225) !important;\\n  --theme-bg-parts: 255, 255, 255 !important;\\n  --theme-sel-bg-parts: 123, 100, 200 !important;\\n  --theme-fg-parts: 20, 20, 20 !important;\\n}\\n\\nhtml,\\nbody,\\n#container,\\n#content {\\n  background-image:\\n    radial-gradient(circle at 18% 18%, rgb(123 100 200 / 20%) 0%, transparent 40%),\\n    radial-gradient(circle at 82% 78%, rgb(123 100 200 / 14%) 0%, transparent 46%),\\n    linear-gradient(145deg, rgb(255 255 255) 0%, rgb(245 245 245) 55%, rgb(235 235 235) 100%),\\n    var(--background) !important;\\n  background-size: auto, auto, auto, cover !important;\\n  background-position: center, center, center, center !important;\\n  background-repeat: no-repeat !important;\\n  background-attachment: fixed !important;\\n}\\n\"\n+}
+```
+
+### 3) Validate mentally (fast checks)
+- **Contrast**: `--theme-fg-parts` must be readable on both primary and secondary backgrounds.
+- **Forcing**: if `forceTheme: true`, ensure `forceDark` matches the palette.
+- **No hard dependency on images** unless you include `images`.
+
+### 4) Hand off
+Name the file as: `<id>.theme.json` (e.g. `banana.theme.json`).
+
+## Advanced: `adaptiveCssVariables` (optional)
+Use only when you want the theme to react cleanly to **Adaptive Theme Colour** in BetterSEQTA+.
+
+What it does:
+- It requests the app to write values derived from the current `--better-main` into CSS custom properties you list.
+- Supports channel bindings by suffix:
+  - `--my-var:r` (red channel as `0..255`)
+  - `--my-var:g` (green channel)
+  - `--my-var:b` (blue channel)
+  - `--my-var` (full colour string)
+
+When to use:
+- Your theme does math/mixing in CSS and needs stable numeric channels.
+
+When NOT to use:
+- Most themes. If your theme looks good with a fixed palette, omit it.
+
diff --git a/src/plugins/built-in/themes/theme-manager.ts b/src/plugins/built-in/themes/theme-manager.ts
index b3bc490a..e37f90e5 100644
--- a/src/plugins/built-in/themes/theme-manager.ts
+++ b/src/plugins/built-in/themes/theme-manager.ts
@@ -25,7 +25,9 @@ type ThemeContent = {
   CanChangeColour?: boolean;
   CustomCSS?: string;
   hideThemeName?: boolean;
+  forceTheme?: boolean;
   forceDark?: boolean;
+  adaptiveCssVariables?: string[];
   images?: { id: string; variableName: string; data: string }[]; // data: base64
 };
 
@@ -35,7 +37,7 @@ export type InstallThemeMeta = {
   serverUpdatedAtSec?: number;
   forceTheme?: boolean;
   adaptiveCssVariables?: string[];
-  images: { id: string; variableName: string; data: string }[]; // data: base64
+  images?: { id: string; variableName: string; data: string }[]; // data: base64
 };
 
 export class ThemeManager {

From 5c4d7e1be33bc6e36b50686229f620e5d805c1f6 Mon Sep 17 00:00:00 2001
From: StroepWafel <109832156+StroepWafel@users.noreply.github.com>
Date: Tue, 21 Apr 2026 21:35:41 +0930
Subject: [PATCH 05/10] Update package.json

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 72bdfc2a..27826d94 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "betterseqtaplus",
-  "version": "3.6.3",
+  "version": "3.6.4",
   "type": "module",
   "description": "Enhance SEQTA Learn's usability and aesthetics! A fork of BetterSEQTA to continue development and add heaps more features!",
   "browserslist": "> 0.5%, last 2 versions, not dead",

From 9c47fa38ae738270eeb7da69e6bc6ff9252a6eb7 Mon Sep 17 00:00:00 2001
From: StroepWafel <109832156+StroepWafel@users.noreply.github.com>
Date: Wed, 22 Apr 2026 06:25:47 +0930
Subject: [PATCH 06/10] fix issue spelling

---
 .cursor/skills/theme-authoring/SKILL.md | 96 -------------------------
 1 file changed, 96 deletions(-)
 delete mode 100644 .cursor/skills/theme-authoring/SKILL.md

diff --git a/.cursor/skills/theme-authoring/SKILL.md b/.cursor/skills/theme-authoring/SKILL.md
deleted file mode 100644
index 58de7286..00000000
--- a/.cursor/skills/theme-authoring/SKILL.md
+++ /dev/null
@@ -1,96 +0,0 @@
----
-name: theme-authoring
-description: Creates BetterSEQTA+ custom themes as `.theme.json` files for import or publishing to the BetterSEQTA theme store. Use when the user asks to make a new theme, adjust theme colors/CSS, or prepare a theme JSON for upload.
----
-
-# Theme authoring (BetterSEQTA+)
-
-## Goal
-Produce a valid `*.theme.json` file that BetterSEQTA+ can install (via theme import or store download).
-
-## Output contract
-Return:
-- The final theme JSON (ready to save as `my-theme.theme.json`)
-- A short list of the main palette values used (accent + background + text)
-
-## Theme JSON schema (practical)
-Required keys:
-- `id`: string (stable identifier; use kebab-case, e.g. `banana-theme`)
-- `name`: string (display name)
-- `description`: string
-- `defaultColour`: string CSS color (e.g. `rgb(...)` or `#RRGGBB`)
-- `CanChangeColour`: boolean
-- `CustomCSS`: string (CSS applied as a `<style>` tag)
-
-Common optional keys:
-- `hideThemeName`: boolean
-- `forceTheme`: boolean (when true, the theme forces light/dark)
-- `forceDark`: boolean (when forcing, `true` = dark, `false` = light)
-- `images`: array of `{ id, variableName, data }` where `data` is base64 PNG (no prefix required, but allowed)
-- `coverImage`: base64 image string (optional)
-- `adaptiveCssVariables`: string[] (advanced; see below)
-
-## Workflow
-### 1) Pick a theme concept + palette
-Decide:
-- **Accent**: set as `defaultColour`
-- **Surfaces**: `--background-primary`, `--background-secondary`
-- **Text**: set `--theme-fg-parts` to a readable RGB triple
-
-If the theme is intended to be “bright” and friendly, default to **forced light**:
-- `forceTheme: true`, `forceDark: false`
-
-If it’s intended to be “night/dark”, default to **forced dark**:
-- `forceTheme: true`, `forceDark: true`
-
-### 2) Write `CustomCSS`
-Use a consistent, minimal set of overrides:
-- In `:root` set:
-  - `--background-primary`, `--background-secondary`
-  - `--theme-offset-bg`, `--theme-offset-bg-more` (slightly darker/lighter than secondary)
-  - `--theme-bg-parts`, `--theme-sel-bg-parts`, `--theme-fg-parts` (RGB triples)
-- Set the page background on:
-  - `html, body, #container, #content`
-  - Use 2–3 subtle `radial-gradient(...)` layers + a `linear-gradient(...)`
-  - Finish with `, var(--background) !important;` so custom backgrounds still work
-
-Recommended template (edit values and gradient stops):
-
-```json
-{
-  "id": "my-theme",
-  "name": "My Theme",
-  "description": "One-line vibe description.",
-  "defaultColour": "rgb(123, 100, 200)",
-  "CanChangeColour": true,
-  "hideThemeName": false,
-  "forceTheme": true,
-  "forceDark": false,
-  "CustomCSS": ":root {\\n  --background-primary: rgb(255, 255, 255) !important;\\n  --background-secondary: rgb(235, 235, 235) !important;\\n  --theme-offset-bg: rgb(245, 245, 245) !important;\\n  --theme-offset-bg-more: rgb(225, 225, 225) !important;\\n  --theme-bg-parts: 255, 255, 255 !important;\\n  --theme-sel-bg-parts: 123, 100, 200 !important;\\n  --theme-fg-parts: 20, 20, 20 !important;\\n}\\n\\nhtml,\\nbody,\\n#container,\\n#content {\\n  background-image:\\n    radial-gradient(circle at 18% 18%, rgb(123 100 200 / 20%) 0%, transparent 40%),\\n    radial-gradient(circle at 82% 78%, rgb(123 100 200 / 14%) 0%, transparent 46%),\\n    linear-gradient(145deg, rgb(255 255 255) 0%, rgb(245 245 245) 55%, rgb(235 235 235) 100%),\\n    var(--background) !important;\\n  background-size: auto, auto, auto, cover !important;\\n  background-position: center, center, center, center !important;\\n  background-repeat: no-repeat !important;\\n  background-attachment: fixed !important;\\n}\\n\"\n+}
-```
-
-### 3) Validate mentally (fast checks)
-- **Contrast**: `--theme-fg-parts` must be readable on both primary and secondary backgrounds.
-- **Forcing**: if `forceTheme: true`, ensure `forceDark` matches the palette.
-- **No hard dependency on images** unless you include `images`.
-
-### 4) Hand off
-Name the file as: `<id>.theme.json` (e.g. `banana.theme.json`).
-
-## Advanced: `adaptiveCssVariables` (optional)
-Use only when you want the theme to react cleanly to **Adaptive Theme Colour** in BetterSEQTA+.
-
-What it does:
-- It requests the app to write values derived from the current `--better-main` into CSS custom properties you list.
-- Supports channel bindings by suffix:
-  - `--my-var:r` (red channel as `0..255`)
-  - `--my-var:g` (green channel)
-  - `--my-var:b` (blue channel)
-  - `--my-var` (full colour string)
-
-When to use:
-- Your theme does math/mixing in CSS and needs stable numeric channels.
-
-When NOT to use:
-- Most themes. If your theme looks good with a fixed palette, omit it.
-

From 0b51db5434b061d5c523c045fe571a969c1a479d Mon Sep 17 00:00:00 2001
From: StroepWafel <109832156+StroepWafel@users.noreply.github.com>
Date: Wed, 22 Apr 2026 06:27:01 +0930
Subject: [PATCH 07/10] Update OpenWhatsNewPopup.ts

---
 src/seqta/utils/Openers/OpenWhatsNewPopup.ts | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/seqta/utils/Openers/OpenWhatsNewPopup.ts b/src/seqta/utils/Openers/OpenWhatsNewPopup.ts
index 255d6623..c23605e2 100644
--- a/src/seqta/utils/Openers/OpenWhatsNewPopup.ts
+++ b/src/seqta/utils/Openers/OpenWhatsNewPopup.ts
@@ -36,8 +36,7 @@ export function OpenWhatsNewPopup(onDismissed?: () => void) {
 
 
       <h1>3.6.4 - Adaptive theme channel bindings</h1>
-      <li>Added adaptive CSS variable channel bindings for custom themes: use <code>--my-var:r</code>, <code>--my-var:g</code>, or <code>--my-var:b</code> in <code>adaptiveCssVariables</code>.</li>
-      <li>Adaptive theme bindings now support both full-colour and single-channel values, enabling more reliable theme math without fragile CSS colour parsing.</li>
+      <li>Added adaptive CSS variable single channel support (r/g/b)</li>
       <h1>3.6.3 - Assessment overview fix</h1>
       <li>Fixed assessments overview failing to load.</li>
       <h1>3.6.2 - Cloud backup, various fixes & SEQTA Engage support</h1>

From 5178408f39c01562bdf2f6fa81b126a3d2b247ed Mon Sep 17 00:00:00 2001
From: StroepWafel <109832156+StroepWafel@users.noreply.github.com>
Date: Wed, 22 Apr 2026 06:28:48 +0930
Subject: [PATCH 08/10] Update OpenWhatsNewPopup.ts

---
 src/seqta/utils/Openers/OpenWhatsNewPopup.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/seqta/utils/Openers/OpenWhatsNewPopup.ts b/src/seqta/utils/Openers/OpenWhatsNewPopup.ts
index c23605e2..76495fc9 100644
--- a/src/seqta/utils/Openers/OpenWhatsNewPopup.ts
+++ b/src/seqta/utils/Openers/OpenWhatsNewPopup.ts
@@ -35,8 +35,8 @@ export function OpenWhatsNewPopup(onDismissed?: () => void) {
     <div class="whatsnewTextContainer" style="height: 50%;overflow-y: auto;">
 
 
-      <h1>3.6.4 - Adaptive theme channel bindings</h1>
-      <li>Added adaptive CSS variable single channel support (r/g/b)</li>
+      <h1>3.6.4 - Patch for alpine theme</h1>
+      <li>Added single channel adaptive CSS variables (r/g/b)</li>
       <h1>3.6.3 - Assessment overview fix</h1>
       <li>Fixed assessments overview failing to load.</li>
       <h1>3.6.2 - Cloud backup, various fixes & SEQTA Engage support</h1>

From c0a8a761052d156ddee6d4ca194cac2cfc96800a Mon Sep 17 00:00:00 2001
From: StroepWafel <contact@stroepwafel.au>
Date: Tue, 19 May 2026 20:19:50 +0930
Subject: [PATCH 09/10] feat: Theme Of The Month

---
 src/background.ts                             |  32 ++-
 src/css/injected.scss                         |  53 +++++
 src/interface/pages/settings/general.svelte   |  67 ++++++
 src/interface/pages/store.svelte              |  27 +++
 src/plugins/built-in/themes/theme-manager.ts  |   6 +-
 src/plugins/monofile.ts                       |   2 +-
 src/seqta/utils/DevApiBase.ts                 |  65 ++++++
 .../utils/Openers/OpenThemeOfTheMonthPopup.ts | 210 ++++++++++++++++++
 src/seqta/utils/Openers/StartupPopupQueue.ts  |  24 +-
 .../utils/openThemeStoreWithHighlight.ts      |  39 ++++
 src/types/storage.ts                          |   2 +
 11 files changed, 520 insertions(+), 7 deletions(-)
 create mode 100644 src/seqta/utils/DevApiBase.ts
 create mode 100644 src/seqta/utils/Openers/OpenThemeOfTheMonthPopup.ts
 create mode 100644 src/seqta/utils/openThemeStoreWithHighlight.ts

diff --git a/src/background.ts b/src/background.ts
index 32f22083..756a9812 100644
--- a/src/background.ts
+++ b/src/background.ts
@@ -9,6 +9,21 @@ import {
   runCloudSettingsPoll,
 } from "./background/cloudSettingsAutoSync";
 
+/**
+ * Session-only dev-mode override of the content API base.
+ *
+ * Stored in a module-level variable (not `chrome.storage`) so it is wiped
+ * automatically when the browser/service-worker process restarts. Content
+ * scripts re-sync this on every page load via `setDevApiBase` so the value
+ * survives transient service-worker terminations within the same browser
+ * session.
+ */
+const DEFAULT_API_BASE = "https://betterseqta.org";
+let DEV_API_BASE: string | null = null;
+function apiBase(): string {
+  return DEV_API_BASE ?? DEFAULT_API_BASE;
+}
+
 function reloadSeqtaPages() {
   const result = browser.tabs.query({});
   function open(tabs: any) {
@@ -29,7 +44,7 @@ type MessageSender = { (response?: unknown): void };
 
 function handleFetchThemes(request: any, sendResponse: MessageSender): boolean {
   const { token } = request;
-  const apiUrl = `https://betterseqta.org/api/themes?type=betterseqta&limit=100&nocache=${Date.now()}`;
+  const apiUrl = `${apiBase()}/api/themes?type=betterseqta&limit=100&nocache=${Date.now()}`;
   const githubUrl = `https://raw.githubusercontent.com/BetterSEQTA/BetterSEQTA-Themes/main/store/themes.json?nocache=${Date.now()}`;
   const headers: Record<string, string> = {};
   if (token) headers["Authorization"] = `Bearer ${token}`;
@@ -57,7 +72,7 @@ function handleFetchThemeDetails(request: any, sendResponse: MessageSender): boo
   }
   const headers: Record<string, string> = {};
   if (token) headers["Authorization"] = `Bearer ${token}`;
-  fetch(`https://betterseqta.org/api/themes/${themeId}`, { cache: "no-store", headers })
+  fetch(`${apiBase()}/api/themes/${themeId}`, { cache: "no-store", headers })
     .then((r) => r.json())
     .then(sendResponse)
     .catch((err) => {
@@ -283,7 +298,7 @@ function handleCloudFavorite(request: any, sendResponse: MessageSender): boolean
     return false;
   }
   const isFavorite = action === "favorite";
-  fetch(`https://betterseqta.org/api/themes/${themeId}/favorite`, {
+  fetch(`${apiBase()}/api/themes/${themeId}/favorite`, {
     method: isFavorite ? "POST" : "DELETE",
     headers: { Authorization: `Bearer ${token}` },
   })
@@ -310,8 +325,19 @@ function isSeqtaOrigin(origin: string): boolean {
   }
 }
 
+function handleSetDevApiBase(request: any): boolean {
+  const url = typeof request?.url === "string" ? request.url.trim() : null;
+  if (url && /^https?:\/\//.test(url)) {
+    DEV_API_BASE = url.replace(/\/$/, "");
+  } else {
+    DEV_API_BASE = null;
+  }
+  return false;
+}
+
 const MESSAGE_HANDLERS: Record<string, MessageHandler> = {
   reloadTabs: () => reloadSeqtaPages(),
+  setDevApiBase: handleSetDevApiBase,
   extensionPages: (req) => {
     browser.tabs.query({}).then((tabs) => {
       for (const tab of tabs) {
diff --git a/src/css/injected.scss b/src/css/injected.scss
index 9c5fe51c..c01c3590 100644
--- a/src/css/injected.scss
+++ b/src/css/injected.scss
@@ -3726,6 +3726,59 @@ div.day-empty {
   color: var(--text-primary);
 }
 
+.whatsnewHeader.themeOfTheMonthHeader {
+  height: auto;
+  min-height: unset;
+}
+.whatsnewHeader.themeOfTheMonthHeader h1 {
+  line-height: 1.2;
+}
+.themeOfTheMonthSubtitle {
+  margin: 0.25rem 0 0;
+  font-size: 0.95rem;
+  font-weight: 500;
+  letter-spacing: 0.01em;
+  text-transform: uppercase;
+  color: color-mix(in srgb, var(--text-primary) 65%, transparent);
+}
+.themeOfTheMonthFooter {
+  display: flex;
+  justify-content: center;
+  padding: 1rem 0;
+}
+.themeOfTheMonthViewButton {
+  appearance: none;
+  border: none;
+  cursor: pointer;
+  padding: 0.65rem 1.25rem;
+  border-radius: 9999px;
+  font-size: 1rem;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+  background: var(--better-pri, #6366f1);
+  color: white;
+  transition: transform 0.15s ease, filter 0.15s ease;
+}
+.themeOfTheMonthViewButton:hover {
+  filter: brightness(1.1);
+  transform: scale(1.03);
+}
+.themeOfTheMonthViewButton:active {
+  transform: scale(0.98);
+}
+
+.bsplus-theme-highlight {
+  animation: bsplusThemeHighlightPulse 1.4s ease-in-out 2;
+}
+@keyframes bsplusThemeHighlightPulse {
+  0%, 100% {
+    box-shadow: 0 0 0 0 color-mix(in srgb, var(--better-pri, #6366f1) 0%, transparent);
+  }
+  50% {
+    box-shadow: 0 0 0 6px color-mix(in srgb, var(--better-pri, #6366f1) 60%, transparent);
+  }
+}
+
 .popup-media-fullscreenable {
   cursor: pointer;
   transition: opacity 0.2s ease-in-out, transform 0.2s ease-in-out;
diff --git a/src/interface/pages/settings/general.svelte b/src/interface/pages/settings/general.svelte
index 2928fffa..3b916dd9 100644
--- a/src/interface/pages/settings/general.svelte
+++ b/src/interface/pages/settings/general.svelte
@@ -15,8 +15,34 @@
   import CloudHeader from "@/interface/components/store/CloudHeader.svelte"
   import { cloudAuth } from "@/seqta/utils/CloudAuth"
   import { showPrivacyNotification } from "@/seqta/utils/Openers/OpenPrivacyNotification"
+  import { showThemeOfTheMonthPopupNow } from "@/seqta/utils/Openers/OpenThemeOfTheMonthPopup"
   import { closeExtensionPopup } from "@/seqta/utils/Closers/closeExtensionPopup"
   import { getSnapshotForUpload } from "@/seqta/utils/cloudSettingsSync"
+  import { getStoredOverride, setApiBase } from "@/seqta/utils/DevApiBase"
+
+  let devApiBaseInput = $state<string>(getStoredOverride() ?? "")
+  let devApiBaseActive = $state<string | null>(getStoredOverride())
+
+  function applyDevApiBase() {
+    const trimmed = devApiBaseInput.trim()
+    if (trimmed === "") {
+      setApiBase(null)
+      devApiBaseActive = null
+      return
+    }
+    if (!/^https?:\/\//.test(trimmed)) {
+      alert("Please enter a full URL starting with http:// or https://")
+      return
+    }
+    setApiBase(trimmed)
+    devApiBaseActive = trimmed.replace(/\/$/, "")
+  }
+
+  function clearDevApiBase() {
+    devApiBaseInput = ""
+    setApiBase(null)
+    devApiBaseActive = null
+  }
 
   import { getAllPluginSettings } from "@/plugins"
   import type { BooleanSetting, StringSetting, NumberSetting, SelectSetting, ButtonSetting, HotkeySetting, ComponentSetting } from "@/plugins/core/types"
@@ -483,6 +509,22 @@
           />
         </div>
       </div>
+      <div class="flex justify-between items-center px-4 py-3">
+        <div class="pr-4">
+          <h2 class="text-sm font-bold">Show Theme of the Month</h2>
+          <p class="text-xs">Fetch and show the current month's popup now (ignores dismissed state)</p>
+        </div>
+        <div>
+          <Button
+            onClick={async () => {
+              closeExtensionPopup();
+              await new Promise((resolve) => setTimeout(resolve, 100));
+              await showThemeOfTheMonthPopupNow();
+            }}
+            text="Show Now"
+          />
+        </div>
+      </div>
       <div class="flex justify-between items-center px-4 py-3">
         <div class="pr-4">
           <h2 class="text-sm font-bold">Export cloud settings JSON</h2>
@@ -492,6 +534,31 @@
           <Button onClick={exportCloudSettingsJsonToFile} text="Export to file" />
         </div>
       </div>
+      <div class="flex flex-col gap-2 px-4 py-3">
+        <div class="flex justify-between items-start gap-3">
+          <div class="pr-4">
+            <h2 class="text-sm font-bold">API Base URL (session only)</h2>
+            <p class="text-xs">Override the content API host for this browser session. Cleared on restart. Affects themes, theme of the month, and other server-driven content.</p>
+            {#if devApiBaseActive}
+              <p class="text-xs mt-1 text-amber-600 dark:text-amber-400">
+                Override active: <span class="font-mono">{devApiBaseActive}</span>
+              </p>
+            {/if}
+          </div>
+        </div>
+        <div class="flex gap-2 items-center">
+          <input
+            type="text"
+            placeholder="https://betterseqta.org"
+            bind:value={devApiBaseInput}
+            class="flex-1 px-2 py-1 text-xs rounded border bg-white dark:bg-zinc-800 border-zinc-300 dark:border-zinc-700 text-zinc-900 dark:text-zinc-100"
+          />
+          <Button onClick={applyDevApiBase} text="Apply" />
+          {#if devApiBaseActive}
+            <Button onClick={clearDevApiBase} text="Clear" />
+          {/if}
+        </div>
+      </div>
     </div>
   {/if}
 </div>
diff --git a/src/interface/pages/store.svelte b/src/interface/pages/store.svelte
index 92bcef14..b1e6649c 100644
--- a/src/interface/pages/store.svelte
+++ b/src/interface/pages/store.svelte
@@ -18,6 +18,7 @@
   import Backgrounds from '../components/store/Backgrounds.svelte'
   import { cloudAuth } from '@/seqta/utils/CloudAuth'
   import SignInToFavoriteModal from '../components/SignInToFavoriteModal.svelte'
+  import { consumePendingHighlightThemeId } from '@/seqta/utils/openThemeStoreWithHighlight'
 
   const themeManager = ThemeManager.getInstance();
   let cloudLoggedIn = $state(cloudAuth.state.isLoggedIn);
@@ -122,13 +123,39 @@
     }
   };
 
+  function focusThemeById(themeId: string) {
+    const match = themes.find((t) => t.id === themeId)
+      ?? themes.find((t) => t.flavours?.some((f) => f.id === themeId));
+    if (match) {
+      activeTab = 'themes';
+      searchTerm = '';
+      displayTheme = match;
+    }
+  }
+
+  function onHighlightThemeEvent(e: Event) {
+    const detail = (e as CustomEvent).detail;
+    if (detail?.themeId && typeof detail.themeId === 'string') {
+      focusThemeById(detail.themeId);
+    }
+  }
+
   // On mount
   onMount(async () => {
+    window.addEventListener('bsplus:highlight-theme', onHighlightThemeEvent);
+
     await fetchThemes();
     await fetchCurrentThemes();
     
     darkMode = (await browser.storage.local.get('DarkMode')).DarkMode === 'true';
     darkMode = $settingsState.DarkMode;
+
+    const pending = consumePendingHighlightThemeId();
+    if (pending) focusThemeById(pending);
+
+    return () => {
+      window.removeEventListener('bsplus:highlight-theme', onHighlightThemeEvent);
+    };
   });
 
   // Filter themes (list is already featured-first, then newest; filter preserves order)
diff --git a/src/plugins/built-in/themes/theme-manager.ts b/src/plugins/built-in/themes/theme-manager.ts
index 0faf1449..ccaeddf5 100644
--- a/src/plugins/built-in/themes/theme-manager.ts
+++ b/src/plugins/built-in/themes/theme-manager.ts
@@ -11,6 +11,7 @@ import { settingsState } from "@/seqta/utils/listeners/SettingsState";
 import debounce from "@/seqta/utils/debounce";
 import { themeUpdates } from "@/interface/hooks/ThemeUpdates";
 import { cloudAuth } from "@/seqta/utils/CloudAuth";
+import { getApiBase } from "@/seqta/utils/DevApiBase";
 import { updateAllColors } from "@/seqta/ui/colors/Manager";
 import {
   clearCustomThemeAdaptiveCssVariables,
@@ -545,7 +546,10 @@ export class ThemeManager {
     }
   }
 
-  private readonly THEME_API_BASE = 'https://betterseqta.org/api';
+  /** Use a getter so dev-mode session-only base URL overrides take effect immediately. */
+  private get THEME_API_BASE(): string {
+    return `${getApiBase()}/api`;
+  }
   private readonly GITHUB_THEMES_BASE = 'https://raw.githubusercontent.com/BetterSEQTA/BetterSEQTA-Themes/main/store/themes';
 
   /**
diff --git a/src/plugins/monofile.ts b/src/plugins/monofile.ts
index 4892c7df..c1a45a6c 100644
--- a/src/plugins/monofile.ts
+++ b/src/plugins/monofile.ts
@@ -105,7 +105,7 @@ export async function finishLoad() {
     console.error("Error during loading cleanup:", err);
   }
 
-  runStartupPopupQueue();
+  void runStartupPopupQueue();
 }
 
 export function GetCSSElement(file: string) {
diff --git a/src/seqta/utils/DevApiBase.ts b/src/seqta/utils/DevApiBase.ts
new file mode 100644
index 00000000..49958da1
--- /dev/null
+++ b/src/seqta/utils/DevApiBase.ts
@@ -0,0 +1,65 @@
+import browser from "webextension-polyfill";
+
+const DEFAULT_BASE = "https://betterseqta.org";
+const KEY = "bsplus_dev_api_base";
+
+/**
+ * Returns the current content-API base URL.
+ *
+ * Reads from `sessionStorage` so a developer can temporarily override the
+ * server for testing. The value is cleared when the browser session ends,
+ * leaving production traffic unaffected for normal users.
+ */
+export function getApiBase(): string {
+  try {
+    if (typeof sessionStorage === "undefined") return DEFAULT_BASE;
+    const v = sessionStorage.getItem(KEY);
+    if (v && /^https?:\/\//.test(v)) return v.replace(/\/$/, "");
+  } catch {
+    // sessionStorage may throw in some restricted contexts; fall back silently.
+  }
+  return DEFAULT_BASE;
+}
+
+/**
+ * Persist a session-scoped override and broadcast it to the background script
+ * so its `fetch` calls hit the same host.
+ *
+ * Pass `null` to clear the override.
+ */
+export function setApiBase(url: string | null): void {
+  try {
+    if (!url) {
+      sessionStorage.removeItem(KEY);
+    } else {
+      sessionStorage.setItem(KEY, url.replace(/\/$/, ""));
+    }
+  } catch {
+    // ignore
+  }
+  void browser.runtime
+    .sendMessage({ type: "setDevApiBase", url: url || null })
+    .catch(() => {});
+}
+
+/** Returns the override URL if one is currently set in this session. */
+export function getStoredOverride(): string | null {
+  try {
+    if (typeof sessionStorage === "undefined") return null;
+    return sessionStorage.getItem(KEY);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Send the current session override to the background script.
+ * Call this early in page load so the background context stays in sync after
+ * service-worker restarts.
+ */
+export function syncApiBaseToBackground(): void {
+  const override = getStoredOverride();
+  void browser.runtime
+    .sendMessage({ type: "setDevApiBase", url: override })
+    .catch(() => {});
+}
diff --git a/src/seqta/utils/Openers/OpenThemeOfTheMonthPopup.ts b/src/seqta/utils/Openers/OpenThemeOfTheMonthPopup.ts
new file mode 100644
index 00000000..a9f0d553
--- /dev/null
+++ b/src/seqta/utils/Openers/OpenThemeOfTheMonthPopup.ts
@@ -0,0 +1,210 @@
+import browser from "webextension-polyfill";
+import stringToHTML from "../stringToHTML";
+import { settingsState } from "../listeners/SettingsState";
+import { openPopup, closePopup } from "./PopupManager";
+import { getApiBase } from "../DevApiBase";
+import { openThemeStoreWithHighlight } from "../openThemeStoreWithHighlight";
+import { cloudAuth } from "../CloudAuth";
+
+/**
+ * Server response shape from `/api/theme-of-the-month/current`.
+ * Hero image is resolved client-side via the theme store API when `theme_id` is set.
+ */
+export interface ThemeOfTheMonthEntry {
+  id: string;
+  month: string;
+  title: string;
+  description: string;
+  cover_image: string | null;
+  theme_id: string | null;
+  theme: { id: string; name: string; slug: string } | null;
+  created_at: number;
+  updated_at: number;
+}
+
+/**
+ * Fetches the current month's Theme of the Month entry from the API.
+ * Returns `null` when no entry is configured for this month, or when the
+ * request fails (we never want a network problem to block other startup
+ * popups).
+ */
+export async function fetchThemeOfTheMonth(): Promise<ThemeOfTheMonthEntry | null> {
+  try {
+    const res = await fetch(`${getApiBase()}/api/theme-of-the-month/current`, {
+      cache: "no-store",
+    });
+    if (!res.ok) return null;
+    const text = await res.text();
+    if (!text) return null;
+    const data = JSON.parse(text);
+    if (!data || typeof data !== "object" || !data.id) return null;
+    return data as ThemeOfTheMonthEntry;
+  } catch (err) {
+    console.warn("[ThemeOfTheMonth] Failed to fetch current entry:", err);
+    return null;
+  }
+}
+
+/** True when we have a new monthly entry the user hasn't dismissed yet. */
+export function shouldShowThemeOfTheMonth(entry: ThemeOfTheMonthEntry | null): boolean {
+  if (!entry) return false;
+  return settingsState.themeOfTheMonthLastSeenId !== entry.id;
+}
+
+function escapeHTML(str: string): string {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+function formatMonthLabel(month: string): string {
+  const [yyyy, mm] = month.split("-");
+  if (!yyyy || !mm) return month;
+  const date = new Date(parseInt(yyyy, 10), parseInt(mm, 10) - 1, 1);
+  return date.toLocaleDateString("en-US", { year: "numeric", month: "long" });
+}
+
+/** Same priority as the theme store: marquee, then cover/banner. */
+function heroUrlFromStoreTheme(theme: {
+  marqueeImage?: string | null;
+  coverImage?: string | null;
+}): string | null {
+  const url = (theme.marqueeImage || theme.coverImage || "").trim();
+  return url || null;
+}
+
+/**
+ * Loads hero image for a store theme via the background script (same path as
+ * {@link ThemeSelector} / theme store detail fetches).
+ */
+export async function fetchThemeStoreHeroImage(themeId: string): Promise<string | null> {
+  try {
+    const token = await cloudAuth.getStoredToken();
+    const res = (await browser.runtime.sendMessage({
+      type: "fetchThemeDetails",
+      themeId,
+      token: token ?? undefined,
+    })) as { success?: boolean; data?: { theme?: { marqueeImage?: string; coverImage?: string } } };
+
+    if (!res?.success || !res?.data?.theme) return null;
+    return heroUrlFromStoreTheme(res.data.theme);
+  } catch (err) {
+    console.warn("[ThemeOfTheMonth] Failed to fetch theme store image:", err);
+    return null;
+  }
+}
+
+/** Linked theme store image, else optional admin-uploaded cover. */
+async function resolvePopupHeroImageUrl(entry: ThemeOfTheMonthEntry): Promise<string | null> {
+  const themeId = entry.theme_id ?? entry.theme?.id;
+  if (themeId) {
+    const fromStore = await fetchThemeStoreHeroImage(themeId);
+    if (fromStore) return fromStore;
+  }
+  const fallback = entry.cover_image?.trim();
+  return fallback || null;
+}
+
+function createHeroImageContainer(imageUrl: string, alt: string): HTMLElement {
+  const container = document.createElement("div");
+  container.classList.add("whatsnewImgContainer");
+
+  const img = document.createElement("img");
+  img.src = imageUrl;
+  img.alt = alt;
+  img.classList.add("whatsnewImg");
+  container.appendChild(img);
+
+  return container;
+}
+
+/**
+ * Renders the Theme of the Month announcement popup.
+ */
+export async function OpenThemeOfTheMonthPopup(
+  entry: ThemeOfTheMonthEntry,
+  onDismissed?: () => void,
+) {
+  if (document.getElementById("whatsnewbk")) {
+    onDismissed?.();
+    return;
+  }
+
+  const monthLabel = formatMonthLabel(entry.month);
+
+  const header = stringToHTML(
+    /* html */ `
+    <div class="whatsnewHeader themeOfTheMonthHeader">
+      <h1>${escapeHTML(entry.title)}</h1>
+      <p class="themeOfTheMonthSubtitle">Theme of the Month · ${escapeHTML(monthLabel)}</p>
+    </div>`,
+  ).firstChild as HTMLElement;
+
+  const heroUrl = await resolvePopupHeroImageUrl(entry);
+  const imageContainer = heroUrl ? createHeroImageContainer(heroUrl, entry.title) : null;
+
+  const descriptionHTML = escapeHTML(entry.description).replace(/\n/g, "<br />");
+  const text = stringToHTML(/* html */ `
+    <div class="whatsnewTextContainer themeOfTheMonthDescription" style="height: 50%; overflow-y: auto; font-size: 1.2rem; line-height: 1.6;">
+      <p>${descriptionHTML}</p>
+    </div>
+  `).firstChild as HTMLElement;
+
+  let footer: HTMLElement | null = null;
+  const linkedThemeId = entry.theme_id ?? entry.theme?.id;
+  const linkedThemeName = entry.theme?.name;
+  if (linkedThemeId && linkedThemeName) {
+    footer = document.createElement("div");
+    footer.classList.add("whatsnewFooter", "themeOfTheMonthFooter");
+
+    const viewBtn = document.createElement("button");
+    viewBtn.type = "button";
+    viewBtn.classList.add("themeOfTheMonthViewButton");
+    viewBtn.textContent = `View "${linkedThemeName}" in the Theme Store`;
+    viewBtn.addEventListener("click", () => {
+      void closePopup();
+      openThemeStoreWithHighlight(linkedThemeId);
+    });
+
+    footer.appendChild(viewBtn);
+  }
+
+  settingsState.themeOfTheMonthLastSeenId = entry.id;
+
+  const content: (Node | null)[] = [];
+  if (imageContainer) content.push(imageContainer);
+  content.push(text);
+  if (footer) content.push(footer);
+
+  openPopup({
+    header,
+    content,
+    afterClose: onDismissed,
+  });
+}
+
+/**
+ * Dev helper: fetch the current month's entry and show the popup immediately,
+ * even if the user has already dismissed it this month.
+ */
+export async function showThemeOfTheMonthPopupNow(): Promise<void> {
+  const entry = await fetchThemeOfTheMonth();
+  if (!entry) {
+    alert(
+      "No Theme of the Month entry for the current month (UTC). Create one in the website admin, or check your dev API base URL.",
+    );
+    return;
+  }
+
+  settingsState.themeOfTheMonthLastSeenId = undefined;
+
+  if (document.getElementById("whatsnewbk")) {
+    await closePopup();
+    await new Promise((resolve) => setTimeout(resolve, 150));
+  }
+
+  await OpenThemeOfTheMonthPopup(entry);
+}
diff --git a/src/seqta/utils/Openers/StartupPopupQueue.ts b/src/seqta/utils/Openers/StartupPopupQueue.ts
index 7bfa4e8a..391c4a68 100644
--- a/src/seqta/utils/Openers/StartupPopupQueue.ts
+++ b/src/seqta/utils/Openers/StartupPopupQueue.ts
@@ -4,20 +4,40 @@ import {
   shouldShowEngageParentsAnnouncement,
   showEngageParentsToast,
 } from "./OpenEngageParentsAnnouncement";
+import {
+  fetchThemeOfTheMonth,
+  OpenThemeOfTheMonthPopup,
+  shouldShowThemeOfTheMonth,
+} from "./OpenThemeOfTheMonthPopup";
+import { syncApiBaseToBackground } from "../DevApiBase";
 
 type QueueStep = (goNext: () => void) => void;
 
 /**
  * Runs startup modals in order: What's New (if the extension just updated),
- * then shows the SEQTA Engage toast (once, non-blocking).
+ * Theme of the Month (when a new monthly entry hasn't been seen), then shows
+ * the SEQTA Engage toast (once, non-blocking).
  */
-export function runStartupPopupQueue() {
+export async function runStartupPopupQueue() {
+  // Make sure the background script knows about any dev-mode API override
+  // before we start firing requests.
+  syncApiBaseToBackground();
+
   const steps: QueueStep[] = [];
 
   if (settingsState.justupdated) {
     steps.push((goNext) => OpenWhatsNewPopup(goNext));
   }
 
+  // Fetch the Theme of the Month before queueing so we don't show an empty
+  // popup if the network or server is unavailable.
+  const themeOfTheMonth = await fetchThemeOfTheMonth();
+  if (shouldShowThemeOfTheMonth(themeOfTheMonth)) {
+    steps.push((goNext) => {
+      void OpenThemeOfTheMonthPopup(themeOfTheMonth!, goNext);
+    });
+  }
+
   function runNext() {
     const step = steps.shift();
     if (step) step(runNext);
diff --git a/src/seqta/utils/openThemeStoreWithHighlight.ts b/src/seqta/utils/openThemeStoreWithHighlight.ts
new file mode 100644
index 00000000..f4eca878
--- /dev/null
+++ b/src/seqta/utils/openThemeStoreWithHighlight.ts
@@ -0,0 +1,39 @@
+import { OpenStorePage } from "@/seqta/ui/renderStore";
+
+/**
+ * Module-level handoff for "open the theme store and highlight this theme".
+ *
+ * The store page is mounted lazily inside a Shadow DOM the first time it
+ * opens, so a `CustomEvent` listener would have to be wired up before mount
+ * (causing a race). Using a shared cell keeps the producer (popup button) and
+ * consumer (store `onMount`) decoupled without that timing constraint.
+ *
+ * The store reads & clears this on mount via {@link consumePendingHighlightThemeId}.
+ */
+let pendingHighlightThemeId: string | null = null;
+
+/** Read and clear the pending theme id (called by the store on mount). */
+export function consumePendingHighlightThemeId(): string | null {
+  const id = pendingHighlightThemeId;
+  pendingHighlightThemeId = null;
+  return id;
+}
+
+/**
+ * Opens the theme store and asks it to focus / highlight the given theme.
+ * If the store is already mounted we dispatch a DOM event so it can react
+ * without remounting; otherwise the store consumes the pending id on mount.
+ */
+export function openThemeStoreWithHighlight(themeId: string): void {
+  pendingHighlightThemeId = themeId;
+
+  const existing = document.getElementById("store");
+  if (existing) {
+    window.dispatchEvent(
+      new CustomEvent("bsplus:highlight-theme", { detail: { themeId } }),
+    );
+    return;
+  }
+
+  OpenStorePage();
+}
diff --git a/src/types/storage.ts b/src/types/storage.ts
index adbaf8c9..29224a07 100644
--- a/src/types/storage.ts
+++ b/src/types/storage.ts
@@ -36,6 +36,8 @@ export interface SettingsState {
   engageParentsAnnouncementShown?: boolean;
   /** One-time announcement: BS Cloud automatic settings sync (last in startup popup queue). */
   bsCloudAutoSyncAnnouncementShown?: boolean;
+  /** ID of the last Theme of the Month entry shown to the user (shows once per new entry). */
+  themeOfTheMonthLastSeenId?: string;
   timeFormat?: string;
   animations: boolean;
   defaultPage: string;

From 6c79fe3588f411e2ea3b09be26d02a0322e7daef Mon Sep 17 00:00:00 2001
From: codefactor-io <support@codefactor.io>
Date: Tue, 19 May 2026 10:53:27 +0000
Subject: [PATCH 10/10] [CodeFactor] Apply fixes

---
 src/seqta/utils/Openers/OpenThemeOfTheMonthPopup.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/seqta/utils/Openers/OpenThemeOfTheMonthPopup.ts b/src/seqta/utils/Openers/OpenThemeOfTheMonthPopup.ts
index a9f0d553..e8f1f0fa 100644
--- a/src/seqta/utils/Openers/OpenThemeOfTheMonthPopup.ts
+++ b/src/seqta/utils/Openers/OpenThemeOfTheMonthPopup.ts
@@ -1,7 +1,7 @@
 import browser from "webextension-polyfill";
 import stringToHTML from "../stringToHTML";
 import { settingsState } from "../listeners/SettingsState";
-import { openPopup, closePopup } from "./PopupManager";
+import { closePopup, openPopup } from "./PopupManager";
 import { getApiBase } from "../DevApiBase";
 import { openThemeStoreWithHighlight } from "../openThemeStoreWithHighlight";
 import { cloudAuth } from "../CloudAuth";