thoth-markup-lang 10.5.0 → 12.0.0

package/thoth.js

@@ -1,20 +1,39 @@
 #!/usr/bin/env node
 
 /**
- * THOTH Engine v10.5.0 - The Sovereign Architect (Intelligence Suite)
- * Lead Developer: Engineer Abdelfatah Abdelhamed
+ * THOTH Engine v12.0.0 - The Sovereign Cloud (Intelligence Suite)
+ * Lead Developer & Architect: Engineer Abdelfatah Abdelhamed 🇪🇬
  * ------------------------------------------------------------------
- * الميزات المدمجة:
+ * الميزات المدمجة (النسخة النهائية):
  * 1. Strict Identification: إلزامية وجود TYPE THOTH في السطر الأول.
  * 2. Middleware Support: نظام Auth Guard المتقدم لتصفية العناصر.
  * 3. Dynamic Meta Engine: توليد وسوم الميتا تلقائياً من سياق البيانات.
  * 4. Dev Server & Live Reload: خادم محلي لمراقبة التغييرات لحظياً.
  * 5. Recursive Data Engine: نظام الـ Loops والـ JSON والـ Variables.
+ * 6. Python-Style Traceback: متتبع أخطاء ذكي ودقيق جداً.
+ * 7. Ultra-Fast Parser: تسريع خوارزميات الـ Indentation.
+ * 8. Sovereign Components: القدرة على تعريف وإعادة استخدام المكونات.
+ * 9. State Management: حقن متغيرات الحالة لإنشاء واجهات تفاعلية.
+ * 10. Layout Engine: نظام شبكات مدمج (Row / Column) بخواص Flexbox.
+ * 11. Smart Routing: نظام تنقل داخلي مدمج لبناء تطبيقات SPA.
+ * 12. API Fetch Engine [NEW]: محرك لاتزامني (Async) لجلب بيانات الـ APIs.
  */
 
 const fs = require('fs');
 const path = require('path');
 const http = require('http');
+const https = require('https');
+
+// --- كلاس تتبع الأخطاء الذكي (Python-Style Error Traceback) ---
+class ThothSyntaxError extends Error {
+    constructor(message, lineNum, lineContent, filePath) {
+        super(message);
+        this.name = 'ThothSyntaxError';
+        this.lineNum = lineNum;
+        this.lineContent = lineContent;
+        this.filePath = filePath;
+    }
+}
 
 // --- القاموس المعماري الشامل ---
 const TAG_MAP = {
@@ -23,17 +42,17 @@ const TAG_MAP = {
     'Header': 'header', 'Footer': 'footer', 'Article': 'article', 'Aside': 'aside',
     'Link': 'a', 'Image': 'img', 'Button': 'button', 'List': 'ul', 'Item': 'li',
     'Input': 'input', 'Form': 'form', 'Label': 'label', 'Break': 'br', 'Line': 'hr',
-    'Main': 'main', 'Layout': 'section'
+    'Main': 'main', 'Layout': 'section',
+    'Row': 'div', 'Column': 'div' 
 };
 
 const VOID_ELEMENTS = ['img', 'br', 'hr', 'input', 'meta', 'link'];
 
-// --- سياق التشغيل السيادي ---
-let dataContext = {};
-let config = {
+// --- سياق التشغيل السيادي العام ---
+let globalConfig = {
     devMode: process.argv.includes('--dev') || process.argv.includes('serve'),
     port: 3000,
-    currentUserRole: 'admin', // القيمة الافتراضية لمحاكاة الميدلوير
+    currentUserRole: 'admin', 
     strictMode: true
 };
 
@@ -46,118 +65,243 @@ if (!command || (!target && command !== 'serve')) {
     process.exit(1);
 }
 
-/**
- * عرض إرشادات الاستخدام التقنية
- */
 function displayUsage() {
     const yellow = '\x1b[33m';
+    const cyan = '\x1b[36m';
     const reset = '\x1b[0m';
     console.log(yellow + '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━' + reset);
-    console.log('\x1b[1m\x1b[32m THOTH INTELLIGENCE SUITE v10.5.0 \x1b[0m');
-    console.log(yellow + ' Lead Architect: Abdelfatah Abdelhamed' + reset);
+    console.log('\x1b[1m\x1b[32m THOTH INTELLIGENCE SUITE v12.0.0 (The Sovereign Cloud) \x1b[0m');
+    console.log(cyan + ' Lead Architect: Engineer Abdelfatah Abdelhamed' + reset);
     console.log(yellow + '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━' + reset);
     console.log(' Usage:');
     console.log('   thoth build [file].thoth    (Production Compilation)');
-    console.log('   thoth serve [file].thoth    (Live Dev Server + Reload)');
+    console.log('   thoth serve [file].thoth    (Live SPA Server + Traceback)');
 }
 
-/**
- * معالجة البيانات الديناميكية @{{key}} و @Variable
- */
+// --- محرك الاتصال الخارجي السيادي (متوافق مع كل نسخ Node) ---
+function fetchJSON(url) {
+    return new Promise((resolve, reject) => {
+        const client = url.startsWith('https') ? https : http;
+        client.get(url, { headers: { 'User-Agent': 'THOTH-Sovereign-Engine/12.0' } }, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                if (res.statusCode >= 200 && res.statusCode < 300) {
+                    try { resolve(JSON.parse(data)); }
+                    catch (e) { reject(new Error('Invalid JSON response format.')); }
+                } else {
+                    reject(new Error(`HTTP Error: ${res.statusCode}`));
+                }
+            });
+        }).on('error', reject);
+    });
+}
+
+const DATA_REGEX = /@\{\{([^}]+)\}\}/g;
 function resolveData(text, context, variables = {}) {
-    // 1. استبدال المتغيرات @Var
     let resolved = text;
     for (const [key, val] of Object.entries(variables)) {
         resolved = resolved.replace(new RegExp(key, 'g'), val);
     }
-    // 2. استبدال بيانات JSON @{{key}}
-    return resolved.replace(/@\{\{([^}]+)\}\}/g, (match, key) => {
+    return resolved.replace(DATA_REGEX, (match, key) => {
         const val = context[key.trim()];
         return val !== undefined ? val : match;
     });
 }
 
+function injectStateText(text, stateVars) {
+    let processedText = text;
+    for (const [key, val] of Object.entries(stateVars)) {
+        const token = `@{{${key}}}`;
+        if (processedText.includes(token)) {
+            processedText = processedText.replace(new RegExp(token, 'g'), `<span data-thoth-state="${key}">${val}</span>`);
+        }
+    }
+    return processedText;
+}
+
+function injectStateBindings(attrs) {
+    const match = attrs.match(/action="([^"]+)"/);
+    if (match) {
+        const actionStr = match[1]; 
+        const jsAction = `thothState.dispatch('${actionStr}')`;
+        return attrs.replace(/action="[^"]+"/, `onclick="${jsAction}"`);
+    }
+    return attrs;
+}
+
 /**
- * محرك التجميع المعماري
+ * المحرك الأساسي (تحول إلى Async/Await لدعم السحابة السيادية)
  */
-function compileThoth(inputPath, isDev = false) {
-    if (!fs.existsSync(inputPath)) throw new Error(`Source Integrity Error: "${inputPath}" not found.`);
-
-    const source = fs.readFileSync(inputPath, 'utf8');
-    const lines = source.split(/\r?\n/);
+async function compileThothEngine(sourceContent, inputPath, isDev = false, isSubCall = false, inheritedContext = {}, inheritedComponents = {}, requestedRoute = '/') {
+    const lines = sourceContent.split(/\r?\n/);
     
-    // --- التحقق من شرط السيادة الأول ---
     if (lines[0].trim() !== "TYPE THOTH") {
-        throw new Error("Architectural Identity Error: File must start with 'TYPE THOTH' to ensure sovereignty.");
+        throw new ThothSyntaxError("Architectural Identity Error: Missing 'TYPE THOTH' protocol.", 1, lines[0], inputPath);
     }
 
     let htmlContent = "";
     let stack = [];
-    let variables = {};
+    
+    let dataContext = { ...inheritedContext.dataContext };
+    let variables = { ...inheritedContext.variables };
+    let stateVars = { ...inheritedContext.stateVars };
+    let componentsContext = { ...inheritedComponents };
+    
     let rawScope = { active: false, type: '', indent: 0 };
     let skipIndent = -1;
     let repeatScope = { active: false, key: '', indent: 0, buffer: [] };
+    
+    let componentScope = { active: false, name: '', indent: 0, buffer: [] };
 
-    for (let i = 1; i < lines.length; i++) { // نبدأ من 1 لتجاوز سطر النوع
+    for (let i = 1; i < lines.length; i++) {
+        const lineNum = i + 1;
         let line = lines[i];
-        const trimmed = line.trim();
-        const indent = line.search(/\S/);
-
+        
+        const trimmed = line.trimStart();
         if (!trimmed || trimmed.startsWith('#')) continue;
+        const indent = line.length - trimmed.length;
+        const fullyTrimmed = trimmed.trimEnd();
 
-        // --- 1. Middleware / Auth Guard ---
         if (skipIndent !== -1) {
             if (indent > skipIndent) continue;
             else skipIndent = -1;
         }
 
-        const authMatch = trimmed.match(/Auth="([^"]+)"/);
+        // --- 1. التنقل الذكي (Smart Routing) ---
+        if (fullyTrimmed.startsWith('Route "')) {
+            const match = fullyTrimmed.match(/Route "([^"]+)"/);
+            const routePath = match ? match[1] : '';
+            if (routePath !== requestedRoute) {
+                skipIndent = indent; 
+            }
+            continue; 
+        }
+
+        // --- 2. Middleware / Auth Guard ---
+        const authMatch = fullyTrimmed.match(/Auth="([^"]+)"/);
         if (authMatch) {
-            if (authMatch[1] !== config.currentUserRole && authMatch[1] !== 'guest') {
+            if (authMatch[1] !== globalConfig.currentUserRole && authMatch[1] !== 'guest') {
                 skipIndent = indent;
                 continue;
             }
         }
 
-        // --- 2. Repeat Logic (Recursive) ---
+        // --- 3. Sovereign Components (Define) ---
+        if (componentScope.active) {
+            if (indent > componentScope.indent) {
+                componentScope.buffer.push(line);
+                continue;
+            } else {
+                componentsContext[componentScope.name] = [...componentScope.buffer];
+                componentScope.active = false;
+                componentScope.buffer = [];
+            }
+        }
+
+        if (fullyTrimmed.startsWith('Define ')) {
+            const colonIdx = fullyTrimmed.indexOf(':');
+            if (colonIdx === -1) throw new ThothSyntaxError("ComponentError: Missing ':' in Define statement.", lineNum, line, inputPath);
+            const compName = fullyTrimmed.substring(7, colonIdx).trim();
+            componentScope.name = compName;
+            componentScope.active = true;
+            componentScope.indent = indent;
+            continue;
+        }
+
+        // --- 4. State Management ---
+        if (fullyTrimmed.startsWith('State ')) {
+            const colonIdx = fullyTrimmed.indexOf(':');
+            if (colonIdx !== -1) {
+                const stateKey = fullyTrimmed.substring(6, colonIdx).trim();
+                const stateVal = fullyTrimmed.substring(colonIdx + 1).trim();
+                stateVars[stateKey] = stateVal;
+                variables[`@{{${stateKey}}}`] = stateVal; 
+            } else {
+                throw new ThothSyntaxError(`StateError: Invalid State syntax. Expected 'State name: value'.`, lineNum, line, inputPath);
+            }
+            continue;
+        }
+
+        // --- 5. API Fetch Engine [NEW] ---
+        if (fullyTrimmed.startsWith('API ')) {
+            const match = fullyTrimmed.match(/API\s+([a-zA-Z0-9_]+)="([^"]+)"/);
+            if (match) {
+                const apiKey = match[1];
+                const apiUrl = match[2];
+                try {
+                    dataContext[apiKey] = await fetchJSON(apiUrl);
+                } catch (err) {
+                    throw new ThothSyntaxError(`APIError: Failed to fetch external data from '${apiUrl}'. ${err.message}`, lineNum, line, inputPath);
+                }
+            } else {
+                throw new ThothSyntaxError("APIError: Invalid API syntax. Expected 'API name=\"URL\"'.", lineNum, line, inputPath);
+            }
+            continue;
+        }
+
+        // --- 6. Repeat Logic (Recursive & Async) ---
         if (repeatScope.active) {
             if (indent > repeatScope.indent) {
                 repeatScope.buffer.push(line);
                 continue;
             } else {
                 const list = dataContext[repeatScope.key] || [];
-                list.forEach(item => {
-                    htmlContent += processBuffer(repeatScope.buffer, item, variables);
-                });
+                if(!Array.isArray(list)) {
+                    throw new ThothSyntaxError(`DataMappingError: '${repeatScope.key}' is not a valid Array in Context.`, lineNum, line, inputPath);
+                }
+                for (const item of list) {
+                    const mergedContext = { dataContext: { ...dataContext, ...item }, variables, stateVars };
+                    htmlContent += await processBuffer(repeatScope.buffer, mergedContext, componentsContext, inputPath, lineNum, requestedRoute);
+                }
                 repeatScope.active = false;
                 repeatScope.buffer = [];
             }
         }
 
-        if (trimmed.startsWith('Repeat Over="')) {
-            repeatScope.key = trimmed.match(/Over="([^"]+)"/)[1];
+        if (fullyTrimmed.startsWith('Repeat Over="')) {
+            const match = fullyTrimmed.match(/Over="([^"]+)"/);
+            if (!match) throw new ThothSyntaxError("LoopError: Invalid Repeat syntax.", lineNum, line, inputPath);
+            repeatScope.key = match[1];
             repeatScope.active = true;
             repeatScope.indent = indent;
             continue;
         }
 
-        // --- 3. Data Ingestion & Variables ---
-        if (trimmed.startsWith('DataSource:')) {
-            const dPath = path.resolve(path.dirname(inputPath), trimmed.split(':')[1].trim());
-            if (fs.existsSync(dPath)) dataContext = JSON.parse(fs.readFileSync(dPath, 'utf8'));
+        // --- 7. DataSource & Variables ---
+        if (fullyTrimmed.startsWith('DataSource:')) {
+            const jsonFileName = fullyTrimmed.split(':')[1].trim();
+            const dPath = path.resolve(path.dirname(inputPath), jsonFileName);
+            if (!fs.existsSync(dPath)) throw new ThothSyntaxError(`MissingDataError: DataSource '${jsonFileName}' not found.`, lineNum, line, inputPath);
+            try {
+                const parsedData = JSON.parse(fs.readFileSync(dPath, 'utf8'));
+                dataContext = { ...dataContext, ...parsedData };
+            } catch(e) {
+                throw new ThothSyntaxError(`JSONParseError: Invalid JSON format in '${jsonFileName}'.`, lineNum, line, inputPath);
+            }
             continue;
         }
 
-        if (trimmed.startsWith('Var ')) {
-            const vParts = trimmed.substring(4).split(':');
+        if (fullyTrimmed.startsWith('Var ')) {
+            const vParts = fullyTrimmed.substring(4).split(':');
             if (vParts.length === 2) variables['@' + vParts[0].trim()] = vParts[1].trim();
+            else throw new ThothSyntaxError(`VariableError: Invalid Var syntax.`, lineNum, line, inputPath);
+            continue;
+        }
+
+        if (fullyTrimmed.startsWith('Import:')) {
+            const importFile = fullyTrimmed.substring(7).trim();
+            const importPath = path.resolve(path.dirname(inputPath), importFile);
+            if (!fs.existsSync(importPath)) throw new ThothSyntaxError(`ImportError: Module '${importFile}' not found.`, lineNum, line, inputPath);
+            const importContent = fs.readFileSync(importPath, 'utf8');
+            const subCall = await compileThothEngine(importContent, importPath, false, true, { dataContext, variables, stateVars }, componentsContext, requestedRoute);
+            htmlContent += subCall.html;
             continue;
         }
 
         line = resolveData(line, dataContext, variables);
         const processedTrimmed = line.trim();
 
-        // --- 4. Raw Code Injection (CSS/JS) ---
         if (rawScope.active) {
             if (indent <= rawScope.indent && processedTrimmed !== "") {
                 rawScope.active = false;
@@ -168,7 +312,6 @@ function compileThoth(inputPath, isDev = false) {
             }
         }
 
-        // --- خوارزمية تحليل الفصل الذكي ---
         let colonIdx = -1;
         let inQuotes = false;
         for (let j = 0; j < processedTrimmed.length; j++) {
@@ -181,7 +324,7 @@ function compileThoth(inputPath, isDev = false) {
 
         const firstSpace = instr.indexOf(' ');
         const tagName = firstSpace !== -1 ? instr.substring(0, firstSpace) : instr;
-        const attrs = firstSpace !== -1 ? instr.substring(firstSpace).trim() : "";
+        let attrs = firstSpace !== -1 ? instr.substring(firstSpace).trim() : "";
 
         if (tagName === "StyleSheet" || tagName === "Scripting") {
             rawScope.active = true;
@@ -191,74 +334,134 @@ function compileThoth(inputPath, isDev = false) {
             continue;
         }
 
-        // إدارة المكدس (Stack Indentation)
+        // --- 8. Component Instantiation ---
+        if (componentsContext[tagName]) {
+            let props = {};
+            const propMatches = attrs.matchAll(/([a-zA-Z0-9_]+)="([^"]+)"/g);
+            for (const match of propMatches) { props[`@${match[1]}`] = match[2]; }
+            
+            let compSource = "TYPE THOTH\n";
+            componentsContext[tagName].forEach(l => { compSource += ' '.repeat(indent) + l + '\n'; });
+            
+            const subMergedVars = { ...variables, ...props };
+            const subRes = await compileThothEngine(compSource, inputPath, false, true, { dataContext, variables: subMergedVars, stateVars }, componentsContext, requestedRoute);
+            htmlContent += subRes.html;
+            continue;
+        }
+
         while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {
             htmlContent += `</${stack.pop().name}>\n`;
         }
 
         const tag = TAG_MAP[tagName] || tagName.toLowerCase();
-        const cleanAttrs = attrs.replace(/Auth="[^"]+"/, '').trim();
+        
+        // --- 9. Layout Engine (Row & Column) ---
+        let injectedStyle = "";
+        if (tagName === 'Row') {
+            injectedStyle = "display:flex; flex-wrap:wrap;";
+            const gapMatch = attrs.match(/gap="([^"]+)"/);
+            if (gapMatch) injectedStyle += ` gap:${gapMatch[1]};`;
+            const alignMatch = attrs.match(/align="([^"]+)"/);
+            if (alignMatch) injectedStyle += ` align-items:${alignMatch[1]};`;
+            attrs = attrs.replace(/(gap|align)="[^"]+"/g, '');
+        } else if (tagName === 'Column') {
+            injectedStyle = "display:flex; flex-direction:column;";
+            const widthMatch = attrs.match(/width="([^"]+)"/);
+            if (widthMatch) injectedStyle += ` flex:0 0 ${widthMatch[1]}; max-width:${widthMatch[1]};`;
+            else injectedStyle += " flex:1;";
+            attrs = attrs.replace(/width="[^"]+"/g, '');
+        }
+
+        let cleanAttrs = attrs.replace(/Auth="[^"]+"/, '').trim();
+        cleanAttrs = injectStateBindings(cleanAttrs);
+
+        if (injectedStyle !== "") {
+            if (cleanAttrs.includes('style="')) cleanAttrs = cleanAttrs.replace(/style="([^"]*)"/, `style="$1 ${injectedStyle.trim()}"`);
+            else cleanAttrs += ` style="${injectedStyle.trim()}"`;
+        }
+
         const open = `<${tag}${cleanAttrs ? ' ' + cleanAttrs : ''}>`;
 
         if (VOID_ELEMENTS.includes(tag)) {
-            htmlContent += open + '\n';
+            htmlContent += ' '.repeat(indent) + open + '\n';
         } else if (val) {
-            htmlContent += `${open}${val}</${tag}>\n`;
+            const finalVal = injectStateText(val, stateVars);
+            htmlContent += ' '.repeat(indent) + `${open}${finalVal}</${tag}>\n`;
         } else {
-            htmlContent += open + '\n';
+            htmlContent += ' '.repeat(indent) + open + '\n';
             stack.push({ name: tag, indent: indent });
         }
     }
 
-    // إغلاق أي تكرار متبقي
+    if (componentScope.active) componentsContext[componentScope.name] = [...componentScope.buffer];
     if (repeatScope.active) {
         const list = dataContext[repeatScope.key] || [];
-        list.forEach(item => { htmlContent += processBuffer(repeatScope.buffer, item, variables); });
+        for (const item of list) {
+            const mergedContext = { dataContext: { ...dataContext, ...item }, variables, stateVars };
+            htmlContent += await processBuffer(repeatScope.buffer, mergedContext, componentsContext, inputPath, lines.length, requestedRoute);
+        }
     }
 
     while (stack.length > 0) htmlContent += `</${stack.pop().name}>\n`;
 
-    return generateBoilerplate(htmlContent, isDev);
+    if (isSubCall) return { html: htmlContent, dataContext, stateVars };
+    return generateBoilerplate(htmlContent, dataContext, stateVars, isDev);
+}
+
+/**
+ * دالة التغليف العامة
+ */
+async function compileThoth(inputPath, isDev = false, requestedRoute = '/') {
+    if (!fs.existsSync(inputPath)) throw new ThothSyntaxError(`Source Integrity Error: File not found.`, 0, "", inputPath);
+    const source = fs.readFileSync(inputPath, 'utf8');
+    const result = await compileThothEngine(source, inputPath, isDev, false, {}, {}, requestedRoute);
+    return result.html;
 }
 
 /**
  * معالجة الـ Buffer داخل الـ Loop
  */
-function processBuffer(buffer, item, variables) {
-    let res = "";
-    let bStack = [];
-    buffer.forEach(l => {
-        const ind = l.search(/\S/);
-        let pLine = resolveData(l, item, variables);
-        const t = pLine.trim();
-        let cIdx = t.indexOf(':');
-        let cmdStr = cIdx !== -1 ? t.substring(0, cIdx).trim() : t;
-        let valStr = cIdx !== -1 ? t.substring(cIdx + 1).trim() : "";
-        
-        const space = cmdStr.indexOf(' ');
-        const tag = TAG_MAP[cmdStr.substring(0, space === -1 ? cmdStr.length : space)] || cmdStr.toLowerCase();
-        
-        while (bStack.length > 0 && bStack[bStack.length - 1].indent >= ind) res += `</${bStack.pop().name}>\n`;
-        
-        const op = `<${tag}${space !== -1 ? ' ' + cmdStr.substring(space).trim() : ''}>`;
-        if (VOID_ELEMENTS.includes(tag)) res += op + '\n';
-        else if (valStr) res += `${op}${valStr}</${tag}>\n`;
-        else { res += op + '\n'; bStack.push({ name: tag, indent: ind }); }
-    });
-    while (bStack.length > 0) res += `</${bStack.pop().name}>\n`;
-    return res;
+async function processBuffer(buffer, scopeContext, componentsContext, filePath, baseLineNum, requestedRoute) {
+    let tempSource = "TYPE THOTH\n";
+    buffer.forEach(l => tempSource += l + "\n");
+    const res = await compileThothEngine(tempSource, filePath, false, true, scopeContext, componentsContext, requestedRoute);
+    return res.html;
 }
 
 /**
- * توليد هيكل HTML5 المعياري مع الـ Meta Tags
+ * توليد هيكل HTML5 المعياري
  */
-function generateBoilerplate(content, isDev) {
+function generateBoilerplate(content, dataContext, stateVars, isDev) {
     const title = dataContext.site_title || "THOTH Sovereign Architecture";
     const desc = dataContext.site_desc || "Engineered by Abdelfatah Abdelhamed";
+    const stateJson = JSON.stringify(stateVars);
     
+    const stateEngineScript = `
+    <script>
+        const thothState = {
+            data: ${stateJson},
+            dispatch: function(actionStr) {
+                if(actionStr.startsWith('set:')) {
+                    let logic = actionStr.replace('set:', '').split('=');
+                    let key = logic[0]; let expr = logic[1];
+                    if(expr.includes('+1')) this.data[key] = parseInt(this.data[key]) + 1;
+                    else if(expr.includes('-1')) this.data[key] = parseInt(this.data[key]) - 1;
+                    else this.data[key] = expr;
+                    this.render();
+                }
+            },
+            render: function() {
+                document.querySelectorAll('[data-thoth-state]').forEach(el => {
+                    let key = el.getAttribute('data-thoth-state');
+                    if(this.data[key] !== undefined) el.innerText = this.data[key];
+                });
+            }
+        };
+    </script>`;
+
     const liveReload = isDev ? `
     <script>
-        console.log('%c THOTH DEV MODE: ACTIVE ', 'background:#D4AF37;color:#000;font-weight:bold;');
+        console.log('%c THOTH CLOUD DEV MODE: ACTIVE ', 'background:#06b6d4;color:#000;font-weight:bold;');
         let lastMod = null;
         setInterval(async () => {
             try {
@@ -270,58 +473,107 @@ function generateBoilerplate(content, isDev) {
         }, 1500);
     </script>` : "";
 
-    return `<!DOCTYPE html>
+    return { html: `<!DOCTYPE html>
 <html lang="ar" dir="rtl">
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="description" content="${desc}">
-    <meta name="generator" content="THOTH Sovereign Engine v10.5.0">
-    <meta name="author" content="Abdelfatah Abdelhamed">
+    <meta name="generator" content="THOTH Sovereign Engine v12.0.0">
+    <meta name="author" content="Engineer Abdelfatah Abdelhamed">
     <title>${title}</title>
 </head>
-<body style="margin:0; background:#050505; color:#fff;">
+<body style="margin:0; background:#020617; color:#f8fafc; font-family:sans-serif;">
 ${content}
+${stateEngineScript}
 ${liveReload}
 </body>
-</html>`;
+</html>`};
+}
+
+function getBrowserTracebackHTML(e) {
+    if (e.name === 'ThothSyntaxError') {
+        const escapedContent = e.lineContent.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+        return `
+        <!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>THOTH Engine Error</title></head>
+        <body style="margin:0; background:#020617; font-family:'Fira Code', monospace; display:flex; align-items:center; justify-content:center; height:100vh;">
+            <div style="background:#0f172a; border:1px solid #ef4444; width:90%; max-width:800px; padding:30px; border-radius:12px; box-shadow:0 0 30px rgba(239, 68, 68, 0.2); color:#e2e8f0;">
+                <div style="border-bottom: 1px solid #334155; padding-bottom:15px; margin-bottom:20px;">
+                    <h2 style="color:#ef4444; margin:0; font-size:1.5rem;">⚠️ THOTH Traceback (most recent call last):</h2>
+                </div>
+                <div style="padding: 10px 0;">
+                    <p style="margin:0 0 10px 0; color:#94a3b8;">File <span style="color:#06b6d4;">"${e.filePath}"</span>, line <span style="color:#f59e0b; font-weight:bold;">${e.lineNum}</span>, in &lt;module&gt;</p>
+                    <div style="background:#000; padding:15px; border-radius:8px; border-left:4px solid #ef4444; overflow-x:auto;">
+                        <div style="color:#f87171;">${e.lineNum} | <span style="color:#e2e8f0;">${escapedContent}</span></div>
+                        <div style="color:#ef4444; margin-top:5px;">&nbsp;&nbsp;&nbsp;&nbsp;^</div>
+                    </div>
+                    <p style="margin:20px 0 0 0; color:#ef4444; font-weight:bold; font-size:1.1rem;">${e.message}</p>
+                </div>
+                <div style="border-top: 1px solid #334155; padding-top:15px; margin-top:20px; text-align:right;">
+                    <button onclick="location.reload()" style="background:#ef4444; color:#fff; padding:8px 24px; border:none; border-radius:6px; cursor:pointer; font-weight:bold; font-family:inherit;">RESTART ENGINE</button>
+                </div>
+            </div>
+        </body></html>`;
+    }
+    return `<body style="background:#000;color:#ff5555;padding:50px;font-family:monospace">
+        <h2 style="border-bottom:2px solid #ff5555;padding-bottom:10px">SOVEREIGN RUNTIME ERROR</h2>
+        <p style="font-size:18px">${e.message}</p>
+        <button onclick="location.reload()" style="background:#ff5555;color:#fff;border:none;padding:10px 20px;cursor:pointer">RETRY</button>
+    </body>`;
+}
+
+function printTerminalError(e) {
+    if (e.name === 'ThothSyntaxError') {
+        console.error('\x1b[31m%s\x1b[0m', `\n⚠️  THOTH Traceback:`);
+        console.error('\x1b[90m%s\x1b[0m', `  File "${e.filePath}", line ${e.lineNum}, in <module>`);
+        console.error(`    ${e.lineContent}`);
+        console.error('\x1b[31m%s\x1b[0m', `    ^`);
+        console.error('\x1b[1m\x1b[31m%s\x1b[0m', `${e.message}\n`);
+    } else {
+        console.error(`\x1b[31m [ERROR] ${e.message}\x1b[0m`);
+    }
 }
 
 // --- طبقة التنفيذ ---
 if (command === 'serve') {
-    const server = http.createServer((req, res) => {
+    const server = http.createServer(async (req, res) => {
+        if (req.url === '/favicon.ico') { res.writeHead(204); return res.end(); }
+
         try {
-            const html = compileThoth(target, true);
-            res.writeHead(200, { 
-                'Content-Type': 'text/html',
-                'Cache-Control': 'no-cache',
-                'ETag': Date.now().toString() 
-            });
+            const parsedUrl = new URL(req.url, `http://localhost:${globalConfig.port}`);
+            const requestedRoute = parsedUrl.pathname;
+
+            // استخدام await عشان المحرك يقدر يجلب بيانات الـ API
+            const html = await compileThoth(target, true, requestedRoute);
+            
+            res.writeHead(200, { 'Content-Type': 'text/html', 'Cache-Control': 'no-cache', 'ETag': Date.now().toString() });
             res.end(html);
         } catch (e) {
+            printTerminalError(e);
             res.writeHead(500, { 'Content-Type': 'text/html' });
-            res.end(`<body style="background:#000;color:#ff5555;padding:50px;font-family:monospace">
-                <h2 style="border-bottom:2px solid #ff5555;padding-bottom:10px">SOVEREIGN COMPILATION ERROR</h2>
-                <p style="font-size:18px">${e.message}</p>
-                <button onclick="location.reload()" style="background:#ff5555;color:#fff;border:none;padding:10px 20px;cursor:pointer">RETRY</button>
-            </body>`);
+            res.end(getBrowserTracebackHTML(e));
         }
     });
 
-    server.listen(config.port, () => {
-        console.log('\x1b[32m%s\x1b[0m', `──────────────────────────────────────────`);
-        console.log(` ✔ SERVER ACTIVE: http://localhost:${config.port}`);
+    server.listen(globalConfig.port, () => {
+        console.log('\x1b[36m%s\x1b[0m', `──────────────────────────────────────────`);
+        console.log(` ✔ SERVER ACTIVE: http://localhost:${globalConfig.port}`);
         console.log(` ✔ ARCHITECTURE: ${target}`);
-        console.log(` ✔ MODE: Intelligence Suite v10.5.0`);
-        console.log('\x1b[32m%s\x1b[0m', `──────────────────────────────────────────`);
+        console.log(` ✔ MODE: The Sovereign Cloud v12.0.0`);
+        console.log('\x1b[36m%s\x1b[0m', `──────────────────────────────────────────`);
     });
+} else if (command === 'build') {
+    // التنفيذ غير المتزامن للبناء
+    (async () => {
+        try {
+            const out = await compileThoth(target, false);
+            fs.writeFileSync(target.replace('.thoth', '.html'), out);
+            console.log(`\x1b[32m [SUCCESS] Architecture materialized: ${target.replace('.thoth', '.html')}\x1b[0m`);
+        } catch (e) {
+            printTerminalError(e);
+            process.exit(1);
+        }
+    })();
 } else {
-    try {
-        const out = compileThoth(target, false);
-        fs.writeFileSync(target.replace('.thoth', '.html'), out);
-        console.log(`\x1b[32m [SUCCESS] Architecture materialized: ${target.replace('.thoth', '.html')}\x1b[0m`);
-    } catch (e) {
-        console.error(`\x1b[31m [ERROR] ${e.message}\x1b[0m`);
-        process.exit(1);
-    }
+     displayUsage();
 }