fix(client): deterministic theme cycle order; document in THEMES/README/ARCH

Author: Cod-e-Codes

ARCHITECTURE.md

@@ -524,6 +524,7 @@ marchat produces two main executables:
 - **Color Schemes**: Comprehensive color palette support
 - **Component Styling**: Granular control over UI elements
 - **Dynamic Loading**: Runtime theme switching
+- **List / cycle order**: Built-in themes in a fixed sequence; custom themes sorted lexicographically by JSON key for `:themes` and Ctrl+T (see **THEMES.md**)
 
 ### Alternative Frontends
 

README.md

@@ -50,6 +50,10 @@ A lightweight terminal chat with real-time messaging over WebSockets, optional E
 #### Toolchain and security
 - **Go 1.25.9** in **`go.mod`**, GitHub Actions, and the **Docker** builder image clears **govulncheck**-listed standard-library issues from **Go 1.25.8** (**crypto/tls**, **crypto/x509**, **archive/tar**, **html/template**, etc.). See **SECURITY.md** for scanner notes: container/SBOM scans often flag dependency **presence** in the image/binary; **`govulncheck ./...`** checks **reachability**. Package-level **pgx** findings (for example **CVE-2026-33815** / **CVE-2026-33816**) may persist while advisory **fixed-version** metadata lags; marchat ships **pgx** v5.9.0+ with related upstream protocol fixes, and default **`govulncheck ./...`** reports no reachable vulnerable call paths.
 
+### Unreleased (main; not in v0.11.0-beta.3 yet)
+
+- **Client themes**: **`:themes`** and **Ctrl+T** use a deterministic order—built-ins `system` → `patriot` → `retro` → `modern`, then custom themes sorted alphabetically by JSON key in `themes.json` ([THEMES.md](THEMES.md)).
+
 ### v0.11.0-beta.2
 - **Go 1.25.8** across CI, Docker, and docs; **SECURITY.md** updates (supported versions, edwards25519 note)
 - **UX**: Terminal-native chrome (reaction/message emoji unchanged); **Alt+M** / **`:msginfo`** toggle message metadata; colorized server banner and client pre-TUI (**`NO_COLOR`** respected)

THEMES.md

@@ -19,6 +19,13 @@ Marchat comes with 4 built-in themes:
 - **retro** - Retro terminal theme with orange, green, and yellow
 - **modern** - Modern dark theme with blue-gray tones
 
+## Theme list and cycle order
+
+`:themes` and **Ctrl+T** use a **stable** order every run:
+
+1. Built-in themes, always in this sequence: **system** → **patriot** → **retro** → **modern**.
+2. Custom themes from `themes.json`, sorted **alphabetically by JSON key** (the quoted identifier for each theme object, e.g. `"dracula"`). Key order in the file does not affect this list; rename the key if you want a different position in the cycle.
+
 ## Custom Theme Format
 
 ```json
@@ -86,15 +93,15 @@ Marchat comes with 4 built-in themes:
 :themes
 ```
 
-This will show all available themes (built-in + custom) with descriptions.
+This will show all available themes (built-in + custom) with descriptions, in the [order above](#theme-list-and-cycle-order).
 
 ### Switch to a Theme
 ```
 :theme dracula
 ```
 
 ### Cycle Through Themes
-Press `Ctrl+T` to cycle through all available themes (built-in and custom).
+Press `Ctrl+T` to cycle through all available themes (built-in and custom) in the [same order](#theme-list-and-cycle-order).
 
 ### Set Default Theme
 Use the interactive configuration or edit your config file:

client/theme_loader.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"sort"
 	"strings"
 
 	"github.com/charmbracelet/lipgloss"
@@ -80,12 +81,14 @@ func LoadCustomThemes() error {
 	return nil
 }
 
-// GetCustomThemeNames returns a list of all custom theme names
+// GetCustomThemeNames returns a list of all custom theme names (sorted by key).
+// Map iteration order is undefined in Go, so we sort for stable Ctrl+T / :themes order.
 func GetCustomThemeNames() []string {
 	names := make([]string, 0, len(customThemes))
 	for name := range customThemes {
 		names = append(names, name)
 	}
+	sort.Strings(names)
 	return names
 }
 

client/theme_loader_test.go

@@ -0,0 +1,28 @@
+package main
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestGetCustomThemeNamesSorted(t *testing.T) {
+	saved := customThemes
+	t.Cleanup(func() { customThemes = saved })
+
+	customThemes = ThemeFile{
+		"zebra": {Name: "Z"},
+		"alpha": {Name: "A"},
+		"moon":  {Name: "M"},
+	}
+	got := GetCustomThemeNames()
+	want := []string{"alpha", "moon", "zebra"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("GetCustomThemeNames() = %v, want %v", got, want)
+	}
+
+	all := ListAllThemes()
+	wantAll := []string{"system", "patriot", "retro", "modern", "alpha", "moon", "zebra"}
+	if !reflect.DeepEqual(all, wantAll) {
+		t.Fatalf("ListAllThemes() = %v, want %v", all, wantAll)
+	}
+}