Reorder theme files + sync script rebuilds custom vars in standard order

Standard themes reorganized: Foundation → Layout → Navigation →
Forms → Components (alphabetical) → Bootstrap → Custom → Extensions

Sync script now fully rebuilds the custom file's :root block in
starter file order, preserving user values while reordering.
Missing variables are inserted at their correct position.

Bump 03.10.04

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

README.md

@@ -9,13 +9,13 @@
  INGROUP: MokoCassiopeia.Documentation
  REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia
  FILE: ./README.md
- VERSION: 03.10.03
+ VERSION: 03.10.04
  BRIEF: Documentation for MokoCassiopeia template
  -->
 
 # MokoCassiopeia → MokoOnyx
 
-> **This template is being renamed to MokoOnyx.** Version 03.10.03 is the bridge release that automatically migrates your settings. After updating, MokoOnyx will be your active template and MokoCassiopeia can be safely uninstalled.
+> **This template is being renamed to MokoOnyx.** Version 03.10.04 is the bridge release that automatically migrates your settings. After updating, MokoOnyx will be your active template and MokoCassiopeia can be safely uninstalled.
 
 **A Modern, Lightweight Joomla Template Based on Cassiopeia**
 

src/joomla.asset.json

@@ -17,7 +17,7 @@
 			"defgroup": "Joomla.Template.Site",
 			"ingroup": "MokoCassiopeia.Template.Assets",
 			"path": "./media/templates/site/mokocassiopeia/joomla.asset.json",
-			"version": "03.10.03",
+			"version": "03.10.04",
 			"brief": "Joomla asset registry for MokoCassiopeia"
 		}
 	},

src/sync_custom_vars.php

@@ -97,28 +97,24 @@ final class MokoCssVarSync
     private static function syncFile(string $starterPath, string $userPath): array
     {
         $starterVars = self::extractVarsWithContext($starterPath);
-        $userVars    = self::extractVarNames($userPath);
+        $userVarsMap = self::extractVarsWithContext($userPath);
+        $userNames   = self::extractVarNames($userPath);
 
+        // Find missing variables
         $missing = [];
         foreach ($starterVars as $name => $declaration) {
-            if (!isset($userVars[$name])) {
+            if (!isset($userNames[$name])) {
                 $missing[$name] = $declaration;
             }
         }
 
-        if (empty($missing)) {
+        // Rebuild the entire :root block in starter file order.
-            return ['added' => [], 'skipped' => []];
+        // User's custom values are preserved; missing vars get starter defaults.
-        }
+        $reordered = self::rebuildInStarterOrder($starterPath, $userVarsMap, $missing);
 
-        // Group missing variables by their section comment header.
+        // Replace the :root block in the user file with the reordered version.
-        $sections = self::groupBySection($missing, $starterPath);
-
-        // Build the injection block.
-        $injection = self::buildInjectionBlock($sections);
-
-        // Insert before the closing } of the :root rule.
         $userCss = file_get_contents($userPath);
-        $userCss = self::injectBeforeRootClose($userCss, $injection);
+        $userCss = self::replaceRootBlock($userCss, $reordered);
 
         // Write back (atomic: write to .tmp then rename).
         $tmpPath = $userPath . '.tmp';
@@ -128,6 +124,104 @@ final class MokoCssVarSync
         return ['added' => array_keys($missing), 'skipped' => []];
     }
 
+    /**
+     * Rebuild all variables in the order they appear in the starter file.
+     * User values are preserved; missing vars use starter defaults.
+     *
+     * @param  string  $starterPath  Path to starter file.
+     * @param  array   $userVars     User's variable name => declaration.
+     * @param  array   $missing      Missing variable name => starter declaration.
+     * @return string  Complete CSS content for inside :root { }.
+     */
+    private static function rebuildInStarterOrder(string $starterPath, array $userVars, array $missing): string
+    {
+        $lines   = file($starterPath, FILE_IGNORE_NEW_LINES);
+        $output  = [];
+        $inRoot  = false;
+        $depth   = 0;
+
+        foreach ($lines as $line) {
+            // Track when we enter :root
+            if (!$inRoot && preg_match('/:root/', $line)) {
+                $inRoot = true;
+                continue;
+            }
+
+            if (!$inRoot) {
+                continue;
+            }
+
+            // Track braces
+            if (strpos($line, '{') !== false) {
+                $depth++;
+                continue;
+            }
+            if (strpos($line, '}') !== false) {
+                $depth--;
+                if ($depth < 0) {
+                    break; // End of :root
+                }
+                continue;
+            }
+
+            // Section comment headers — always include
+            if (preg_match('/\/\*\s*=+\s*.+?\s*=+\s*\*\//', $line)) {
+                $output[] = $line;
+                continue;
+            }
+
+            // Regular comments — include
+            if (preg_match('/^\s*\/\*/', $line) || preg_match('/^\s*\*/', $line)) {
+                $output[] = $line;
+                continue;
+            }
+
+            // Blank lines — include
+            if (trim($line) === '') {
+                $output[] = '';
+                continue;
+            }
+
+            // Variable declaration
+            if (preg_match('/^\s*(--[\w-]+)\s*:/', $line, $m)) {
+                $name = trim($m[1]);
+                if (isset($userVars[$name])) {
+                    // Use the user's custom value
+                    $output[] = $userVars[$name];
+                } elseif (isset($missing[$name])) {
+                    // New variable — use starter default
+                    $output[] = $missing[$name];
+                }
+                continue;
+            }
+
+            // Other lines (e.g. color-scheme) — include as-is
+            $output[] = $line;
+        }
+
+        return implode("\n", $output);
+    }
+
+    /**
+     * Replace the content inside :root { ... } with new content.
+     */
+    private static function replaceRootBlock(string $css, string $newContent): string
+    {
+        $rootStart = preg_match('/:root[^{]*\{/', $css, $m, PREG_OFFSET_CAPTURE);
+        if (!$rootStart) {
+            return $css;
+        }
+
+        $openBrace = $m[0][1] + strlen($m[0][0]);
+        $closeBrace = self::findRootClosingBrace($css);
+
+        if ($closeBrace === false) {
+            return $css;
+        }
+
+        return substr($css, 0, $openBrace) . "\n" . $newContent . "\n" . substr($css, $closeBrace);
+    }
+
     /**
      * Extract CSS custom property declarations with their full text (name: value).
      * Only extracts from the first :root block.

src/templateDetails.xml

@@ -39,13 +39,13 @@
 		</server>
 	</updateservers>
 	<name>MokoCassiopeia</name>
-	<version>03.10.03</version>
+	<version>03.10.04</version>
 	<scriptfile>script.php</scriptfile>
 	<creationDate>2026-04-15</creationDate>
 	<author>Jonathan Miller || Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>
 	<copyright>(C)GNU General Public License Version 3 - 2026 Moko Consulting</copyright>
-	<description><![CDATA[<p><img src="https://img.shields.io/badge/version-03.10.03-blue.svg?logo=v&amp;logoColor=white" alt="Version 03.10.03" /> <img src="https://img.shields.io/badge/license-GPL--3.0--or--later-green.svg?logo=gnu&amp;logoColor=white" alt="License" /> <img src="https://img.shields.io/badge/Joomla-5.x%20%7C%206.x-red.svg?logo=joomla&amp;logoColor=white" alt="Joomla" /> <img src="https://img.shields.io/badge/PHP-8.1%2B-777BB4.svg?logo=php&amp;logoColor=white" alt="PHP" /></p> <h3>MokoCassiopeia Template Description</h3> <p>  <strong>MokoCassiopeia</strong> continues Joomla's tradition of space-themed default templates—  building on the legacy of <em>Solarflare</em> (Joomla 1.0), <em>Milkyway</em> (Joomla 1.5),  and <em>Protostar</em> (Joomla 3.0). </p> <p>  This template is a customized fork of the <strong>Cassiopeia</strong> template introduced in Joomla 4,  preserving its modern, accessible, and mobile-first foundation while introducing new stylistic  enhancements and structural refinements specifically tailored for use by Moko Consulting. </p>  <h4>Custom Colour Themes</h4> <p>  Starter palette files are included with the template. To create a custom colour scheme,  copy <code>templates/mokocassiopeia/templates/light.custom.css</code> to  <code>media/templates/site/mokocassiopeia/css/theme/light.custom.css</code>,  or <code>templates/mokocassiopeia/templates/dark.custom.css</code> to  <code>media/templates/site/mokocassiopeia/css/theme/dark.custom.css</code>.  Customise the CSS variables to match your brand, then activate your palette in  <em>System → Site Templates → MokoCassiopeia → Theme tab</em>  by selecting "Custom" for the Light or Dark Mode Palette.  A full variable reference is available in the <em>CSS Variables</em> tab in template options. </p>  <h4>Custom CSS &amp; JavaScript</h4> <p>  For site-specific styles and scripts that should survive template updates, create the following files: </p> <ul>  <li><code>media/templates/site/mokocassiopeia/css/user.css</code> — loaded on every page for custom CSS overrides.</li>  <li><code>media/templates/site/mokocassiopeia/js/user.js</code> — loaded on every page for custom JavaScript.</li> </ul> <p>  These files are gitignored and will not be overwritten by template updates. </p>  <h4>Code Attribution</h4> <p>  This template is based on the original <strong>Cassiopeia</strong> template developed by the  <a href="https://www.joomla.org" target="_blank" rel="noopener">Joomla! Project</a> and released under the GNU General Public License. </p> <p>  Modifications and enhancements have been made by Moko Consulting in accordance with open-source licensing standards. </p> <p>  It includes integration with  <a href="https://afeld.github.io/bootstrap-toc/" target="_blank" rel="noopener">Bootstrap TOC</a>,  an open-source table of contents generator by A. Feld, licensed under the MIT License. </p> <p>  All third-party libraries and assets remain the property of their respective authors and are credited within their source files where applicable. </p>]]></description>
+	<description><![CDATA[<p><img src="https://img.shields.io/badge/version-03.10.04-blue.svg?logo=v&amp;logoColor=white" alt="Version 03.10.04" /> <img src="https://img.shields.io/badge/license-GPL--3.0--or--later-green.svg?logo=gnu&amp;logoColor=white" alt="License" /> <img src="https://img.shields.io/badge/Joomla-5.x%20%7C%206.x-red.svg?logo=joomla&amp;logoColor=white" alt="Joomla" /> <img src="https://img.shields.io/badge/PHP-8.1%2B-777BB4.svg?logo=php&amp;logoColor=white" alt="PHP" /></p> <h3>MokoCassiopeia Template Description</h3> <p>  <strong>MokoCassiopeia</strong> continues Joomla's tradition of space-themed default templates—  building on the legacy of <em>Solarflare</em> (Joomla 1.0), <em>Milkyway</em> (Joomla 1.5),  and <em>Protostar</em> (Joomla 3.0). </p> <p>  This template is a customized fork of the <strong>Cassiopeia</strong> template introduced in Joomla 4,  preserving its modern, accessible, and mobile-first foundation while introducing new stylistic  enhancements and structural refinements specifically tailored for use by Moko Consulting. </p>  <h4>Custom Colour Themes</h4> <p>  Starter palette files are included with the template. To create a custom colour scheme,  copy <code>templates/mokocassiopeia/templates/light.custom.css</code> to  <code>media/templates/site/mokocassiopeia/css/theme/light.custom.css</code>,  or <code>templates/mokocassiopeia/templates/dark.custom.css</code> to  <code>media/templates/site/mokocassiopeia/css/theme/dark.custom.css</code>.  Customise the CSS variables to match your brand, then activate your palette in  <em>System → Site Templates → MokoCassiopeia → Theme tab</em>  by selecting "Custom" for the Light or Dark Mode Palette.  A full variable reference is available in the <em>CSS Variables</em> tab in template options. </p>  <h4>Custom CSS &amp; JavaScript</h4> <p>  For site-specific styles and scripts that should survive template updates, create the following files: </p> <ul>  <li><code>media/templates/site/mokocassiopeia/css/user.css</code> — loaded on every page for custom CSS overrides.</li>  <li><code>media/templates/site/mokocassiopeia/js/user.js</code> — loaded on every page for custom JavaScript.</li> </ul> <p>  These files are gitignored and will not be overwritten by template updates. </p>  <h4>Code Attribution</h4> <p>  This template is based on the original <strong>Cassiopeia</strong> template developed by the  <a href="https://www.joomla.org" target="_blank" rel="noopener">Joomla! Project</a> and released under the GNU General Public License. </p> <p>  Modifications and enhancements have been made by Moko Consulting in accordance with open-source licensing standards. </p> <p>  It includes integration with  <a href="https://afeld.github.io/bootstrap-toc/" target="_blank" rel="noopener">Bootstrap TOC</a>,  an open-source table of contents generator by A. Feld, licensed under the MIT License. </p> <p>  All third-party libraries and assets remain the property of their respective authors and are credited within their source files where applicable. </p>]]></description>
 	<inheritable>1</inheritable>
 	<files>
 		<filename>component.php</filename>

updates.xml

@@ -1,7 +1,7 @@
 <?xml version='1.0' encoding='UTF-8'?>
 <!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
  SPDX-License-Identifier: GPL-3.0-or-later
- VERSION: 03.10.03
+ VERSION: 03.10.04
  -->
 
 <updates>
@@ -13,11 +13,11 @@
     <element>mokocassiopeia</element>
     <type>template</type>
     <client>site</client>
-    <version>03.10.03</version>
+    <version>03.10.04</version>
     <creationDate>2026-04-18</creationDate>
     <infourl title='MokoCassiopeia Dev'>https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia/releases/tag/development</infourl>
     <downloads>
-      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia/releases/download/development/mokocassiopeia-03.10.03-dev.zip</downloadurl>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia/releases/download/development/mokocassiopeia-03.10.04-dev.zip</downloadurl>
     </downloads>
     <sha256>a7bc2dbc7abeb91a8e079c4d29b8c77366a28066bcf963b01c351593865f0f7c</sha256>
     <tags><tag>development</tag></tags>
@@ -34,11 +34,11 @@
     <element>mokocassiopeia</element>
     <type>template</type>
     <client>site</client>
-    <version>03.10.03</version>
+    <version>03.10.04</version>
     <creationDate>2026-04-14</creationDate>
     <infourl title='MokoCassiopeia Alpha'>https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia/releases/tag/alpha</infourl>
     <downloads>
-      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia/releases/download/alpha/mokocassiopeia-03.10.03-alpha.zip</downloadurl>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia/releases/download/alpha/mokocassiopeia-03.10.04-alpha.zip</downloadurl>
     </downloads>
     <sha256>c2660acdf7389244462485f7ab4c286e9f851366a148acc16739a184576f7932</sha256>
     <tags><tag>alpha</tag></tags>
@@ -55,11 +55,11 @@
     <element>mokocassiopeia</element>
     <type>template</type>
     <client>site</client>
-    <version>03.10.03</version>
+    <version>03.10.04</version>
     <creationDate>2026-04-14</creationDate>
     <infourl title='MokoCassiopeia Beta'>https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia/releases/tag/beta</infourl>
     <downloads>
-      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia/releases/download/beta/mokocassiopeia-03.10.03-beta.zip</downloadurl>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia/releases/download/beta/mokocassiopeia-03.10.04-beta.zip</downloadurl>
     </downloads>
     <sha256>4cbe4fc379182ef17580396e7d12ce4ce95a90017ef364b922bdc2d04b0b3d97</sha256>
     <tags><tag>beta</tag></tags>
@@ -76,12 +76,12 @@
     <element>mokocassiopeia</element>
     <type>template</type>
     <client>site</client>
-    <version>03.10.03</version>
+    <version>03.10.04</version>
     <creationDate>2026-04-14</creationDate>
     <infourl title='MokoCassiopeia RC'>https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia/releases/tag/release-candidate</infourl>
     <downloads>
-      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia/releases/download/release-candidate/mokocassiopeia-03.10.03-rc.zip</downloadurl>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia/releases/download/release-candidate/mokocassiopeia-03.10.04-rc.zip</downloadurl>
-      <downloadurl type='full' format='zip'>https://github.com/mokoconsulting-tech/MokoCassiopeia/releases/download/release-candidate/mokocassiopeia-03.10.03-rc.zip</downloadurl>
+      <downloadurl type='full' format='zip'>https://github.com/mokoconsulting-tech/MokoCassiopeia/releases/download/release-candidate/mokocassiopeia-03.10.04-rc.zip</downloadurl>
     </downloads>
     <sha256>c2660acdf7389244462485f7ab4c286e9f851366a148acc16739a184576f7932</sha256>
     <tags><tag>rc</tag></tags>
@@ -98,12 +98,12 @@
     <element>mokocassiopeia</element>
     <type>template</type>
     <client>site</client>
-    <version>03.10.03</version>
+    <version>03.10.04</version>
     <creationDate>2026-04-14</creationDate>
     <infourl title='MokoCassiopeia'>https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia/releases/tag/v03</infourl>
     <downloads>
-      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia/releases/download/v03/mokocassiopeia-03.10.03.zip</downloadurl>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoCassiopeia/releases/download/v03/mokocassiopeia-03.10.04.zip</downloadurl>
-      <downloadurl type='full' format='zip'>https://github.com/mokoconsulting-tech/MokoCassiopeia/releases/download/v03/mokocassiopeia-03.10.03.zip</downloadurl>
+      <downloadurl type='full' format='zip'>https://github.com/mokoconsulting-tech/MokoCassiopeia/releases/download/v03/mokocassiopeia-03.10.04.zip</downloadurl>
     </downloads>
     <sha256>c2660acdf7389244462485f7ab4c286e9f851366a148acc16739a184576f7932</sha256>
     <tags><tag>stable</tag></tags>