thoth-markup-lang 11.0.0 → 12.0.1

package/README.md

@@ -1,43 +1,304 @@
-# THOTH: The Sovereign Intelligence Suite (v11.0.0 Pulse Edition)
+# 𓂀 THOTH: The Sovereign Web Intelligence Engine
+### v12.0.0 — Sovereign Cloud • Async Core • Reactive Architecture
 
 <p align="center">
-  <img src="https://img.shields.io/npm/v/thoth-markup-lang?style=for-the-badge&color=06b6d4&logo=npm" alt="NPM Version" />
-  <img src="https://img.shields.io/badge/Version-11.0.0--Pulse-f59e0b?style=for-the-badge" alt="Pulse Version" />
-  <img src="https://img.shields.io/badge/Engineered_In-Egypt_🇪🇬-020617?style=for-the-badge&logo=code" alt="Egypt" />
+  <img src="https://img.shields.io/npm/v/thoth-markup-lang?style=for-the-badge&color=06b6d4&logo=npm" />
+  <img src="https://img.shields.io/badge/Core-Async%20Non--Blocking-0ea5e9?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Architecture-Sovereign-f59e0b?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Rendering-Reactive%20Engine-22c55e?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Built%20In-Egypt%20🇪🇬-020617?style=for-the-badge" />
 </p>
 
-**The Binary Wisdom of Web Architecture.** THOTH is a high-performance, sovereign, indentation-based markup language and recursive runtime engine. It eliminates structural noise, removes bracket chaos, and redefines web development through pure, architectural logic.
+<p align="center">
+  <b>Structure is Truth • Logic is Indentation • Control is Sovereignty</b>
+</p>
+
+---
+
+## 🧠 What is THOTH?
+
+**THOTH** is a next-generation **Asynchronous Reactive Web Engine** designed to eliminate the structural and cognitive overhead of modern frontend development.
+
+It is not:
+- ❌ A framework  
+- ❌ A wrapper  
+- ❌ A templating engine  
+
+It is:
+- ✅ A **unified architecture layer**
+- ✅ A **runtime + syntax + philosophy**
+- ✅ A **replacement for fragmented stacks**
+
+> You don’t “build UI” with THOTH… you **define systems**.
+
+---
+
+## 🚨 The Problem THOTH Solves
+
+Modern web stacks suffer from:
+
+- Dependency hell (React, Vite, Redux, Axios…)
+- Boilerplate explosion
+- Context switching (HTML + CSS + JS)
+- Manual state wiring
+- Routing complexity
+- API integration overhead
+
+### THOTH Response:
+
+✔ Zero-bracket syntax  
+✔ Native state engine  
+✔ Built-in SPA routing  
+✔ Direct API binding  
+✔ No external JS required for core logic  
+✔ Single unified architecture file  
+
+---
+
+## 🏗️ Sovereign Scaffolding System [REVOLUTION]
+
+```bash
+thoth create my-app
+```
+
+### Instantly Generates:
+
+```
+/my-app
+ ├── index.thoth
+ ├── /components
+ ├── /data
+ ├── /pages
+ ├── thoth.config.json
+```
+
+### Built for:
+- Rapid prototyping
+- Enterprise architecture
+- Scalable systems
+
+---
+
+## 💎 Core Engine Capabilities
+
+### ☁️ Sovereign Cloud Engine (Native API Layer)
+```text
+API users="https://api.example.com/users"
+```
+
+- Async by default
+- Non-blocking rendering
+- Auto binding to UI nodes
 
 ---
 
-## 🏛️ Architectural Philosophy
+### ⚡ Native Reactive State Engine
+```text
+State energy: 0
+```
 
-THOTH represents a monumental paradigm shift from "tag-heavy" legacy markup to **Recursive Indentation Logic**. With the release of **v11.0.0 (Pulse Edition)**, the engine introduces an ultra-fast parsing core and Python-style error handling, enforcing absolute structural purity. It requires all sovereign files to declare their identity with the `TYPE THOTH` protocol, ensuring architectural integrity and preventing unauthorized code execution.
+- Instant UI updates
+- No virtual DOM diffing
+- No hooks / reducers
 
-- **Official Website:** [THOTH Language Portal](https://honeydew-pigeon-679592.hostingersite.com/)
-- **Lead Architect:** Engineer Abdelfatah Abdelhamed
+---
+
+### 🌐 Smart SPA Routing Engine
+```text
+Route "/":
+Route "/dashboard":
+Route "/system":
+```
+
+- History API handled internally
+- Zero configuration
+- Automatic DOM hydration
 
 ---
 
-## 💎 Intelligence Suite Features (v11.0.0 Pulse)
+### 📐 Native Layout System (Flex Engine)
+```text
+Row gap="20px" align="center":
+Column width="300px":
+```
 
-* **⚡ Ultra-Fast Parser Core [NEW]:** Upgraded O(n) string manipulation algorithms for blazing-fast indentation computation and rendering.
-* **🐞 Python-Style Tracebacks [NEW]:** Intelligent error handling that pinpoints exact file, line number, and syntax faults in both Terminal and a Browser Overlay.
-* **🛡️ Strict Identification:** Mandatory `TYPE THOTH` protocol header to ensure uncompromised file sovereignty.
-* **💎 Zero-Bracket Architecture:** Eliminates opening/closing DOM tags, reducing syntax noise by up to 70%.
-* **🔗 Recursive Data Binding:** Native integration with JSON flat-file databases using `@{{key}}` syntax.
-* **🔐 Procedural Middleware (Auth Guard):** Secure structural DOM nodes natively using `Auth="role"` attributes.
-* **🚀 Pulse Dev Server & Live Reload:** Integrated HTTP server with automated browser synchronization and state tracking.
-* **🔍 Advanced Meta SEO Engine:** Automated generation of HTML5 Meta Tags directly from your JSON data context.
-* **📦 Scoped Components:** Modular file architecture and management through the `Import:` directive.
-* **💉 Hybrid Injection:** Native support for scoped `StyleSheet` (Raw CSS) and `Scripting` (Raw JS) inside the `.thoth` environment.
+- No Tailwind
+- No Bootstrap
+- Pure structural layout logic
 
 ---
 
-## 🚀 Technical Implementation
+### 🧩 Sovereign Component System
+```text
+Define Card:
+    Box:
+        Text: @{{title}}
+```
+
+- Reusable
+- Stateless or stateful
+- Fully isolated
+
+---
 
-### 1. Global Installation
-Install the THOTH Engine globally via NPM to access the sovereign CLI:
+### 🔗 Recursive Data Binding Engine
+```text
+Text: @{{username}}
+```
+
+- JSON / API binding
+- Deep nesting support
+- Zero transformation layer
+
+---
+
+### 🔐 Structural Security (Auth Guards)
+```text
+Header Auth="admin":
+```
+
+- Built-in access control
+- DOM-level protection
+
+---
+
+### 🐞 Intelligent Traceback System
+```text
+File "app.thoth", line 22
+APIError: Invalid endpoint
+```
+
+- Precise debugging
+- Developer-friendly errors
+- Runtime + overlay support
+
+---
 
+## 🚀 Master Example (Full System)
+
+```text
+TYPE THOTH
+
+# Data & Imports
+DataSource: data/config.json
+Import: components/Navbar.thoth
+
+# API Layer
+API users="https://jsonplaceholder.typicode.com/users"
+
+# State Layer
+State clicks: 0
+
+# Root Architecture
+Container class="app-shell":
+
+    Navbar title="THOTH Engine"
+
+    Route "/":
+        Column align="center":
+
+            Title: "Sovereign Cloud Interface"
+
+            Row gap="20px":
+                Repeat Over="users":
+                    Box class="card":
+                        Sub: @{{name}}
+                        Text: @{{email}}
+
+            Row:
+                Text: "Clicks: @{{clicks}}"
+                Button action="set:clicks=clicks+1":
+                    "Inject Signal"
+
+    Route "/system":
+        Column:
+            Sub: "Diagnostics"
+            Text: "All systems operational."
+```
+
+---
+
+## ⚙️ CLI Commands
+
+### Install Engine
 ```bash
-npm install -g thoth-markup-lang
+npm install -g thoth-markup-lang
+```
+
+### Run Dev Server
+```bash
+thoth serve index.thoth
+```
+
+### Build Production
+```bash
+thoth build index.thoth
+```
+
+---
+
+## 🧬 Architecture Keywords (SEO + Indexing)
+
+Asynchronous Web Engine  
+Reactive UI Engine  
+No-JavaScript Framework Alternative  
+Zero-Bracket Markup Language  
+Indentation-Based Syntax Engine  
+SPA Without React  
+Native State Management Engine  
+API-First Frontend Architecture  
+Unified Web Stack  
+Declarative Web Systems  
+Non-Blocking Rendering Engine  
+Component-Based Architecture  
+Modern Web Engine 2026  
+Frontend Without Frameworks  
+Alternative to React / Vue / Angular  
+Sovereign Architecture System  
+
+---
+
+## 🔥 Competitive Comparison
+
+| Feature | React / Vue | THOTH |
+|--------|------------|-------|
+| Setup Complexity | High | **Minimal** |
+| State Management | External | **Native** |
+| Routing | Library-based | **Built-in** |
+| API Calls | Manual | **Native** |
+| Syntax | JSX / Templates | **Indentation Logic** |
+| Performance | Virtual DOM | **Direct Render Engine** |
+
+---
+
+## 🏛️ Core Philosophy
+
+> “The web is not broken…  
+> developers just built too many layers on top of it.”
+
+THOTH removes the layers.
+
+---
+
+## 🌍 Vision
+
+THOTH aims to:
+
+- Replace frontend frameworks
+- Simplify web architecture
+- Reduce dev time by 70%+
+- Enable true system-level thinking
+
+---
+
+## 👑 Final Statement
+
+> “You don’t scale code…  
+> you scale architecture.”
+
+---
+
+<p align="center">
+  <b>Architected by Abdelfatah Abdelhamed</b><br>
+  <i>Egypt 🇪🇬 • Sovereign Systems Engineering</i>
+</p>

package/engine.php

@@ -1,15 +1,20 @@
 <?php
 /**
- * THOTH Sovereign Runtime Engine v11.0 - Pulse Edition
+ * THOTH Sovereign Runtime Engine v12.0.0 - The Sovereign Cloud
  * Architect: Engineer Abdelfatah Abdelhamed 🇪🇬
  * --------------------------------------------------
- * الميزات المدمجة (النسخة المطورة):
+ * الميزات المدمجة (النسخة النهائية):
  * 1. التوثيق المعماري: إلزامية وجود TYPE THOTH في السطر الأول.
  * 2. نظام Middleware (Auth Guard): التحكم الكامل في صلاحيات الوصول.
  * 3. نظام البيانات الديناميكي: JSON Binding & Recursive Loops.
  * 4. نظام Meta SEO الذكي: توليد عناصر Meta بناءً على البيانات.
  * 5. Python-Style Traceback: متتبع أخطاء ذكي يحدد السطر ونوع الخطأ بدقة.
  * 6. High-Performance Core: تسريع التحليل باستخدام دوال PHP الحديثة.
+ * 7. Sovereign Components: القدرة على تعريف وإعادة استخدام المكونات.
+ * 8. State Management: حقن متغيرات الحالة لإنشاء واجهات تفاعلية.
+ * 9. Layout Engine: نظام شبكات مدمج (Row / Column) بخواص Flexbox.
+ * 10. Smart Routing: نظام تنقل داخلي مدمج لبناء تطبيقات SPA.
+ * 11. API Fetch Engine [NEW]: جلب البيانات الخارجية برمجياً بدون كتابة JS.
  */
 
 session_start();
@@ -32,7 +37,8 @@ class ThothEngine {
         'Header' => 'header', 'Footer' => 'footer', 'Bold' => 'strong', 
         'Link' => 'a', 'Image' => 'img', 'List' => 'ul', 'Item' => 'li', 
         'Button' => 'button', 'Input' => 'input', 'Break' => 'br', 
-        'Line' => 'hr', 'Layout' => 'main'
+        'Line' => 'hr', 'Layout' => 'main',
+        'Row' => 'div', 'Column' => 'div'
     ];
 
     private $voidTags = ['img', 'br', 'hr', 'input', 'meta', 'link'];
@@ -41,6 +47,9 @@ class ThothEngine {
     private $devMode = true; 
     private $currentLine = 0;
     private $currentFile = "";
+    
+    private $components = []; 
+    private $stateVars = [];  
 
     /**
      * المدخل الرئيسي للمحرك
@@ -60,7 +69,10 @@ class ThothEngine {
         if ($firstLine !== "TYPE THOTH") {
             return $this->devErrorOverlay("SyntaxError: Missing Identity Protocol. File must begin with TYPE THOTH.", 1, $lines[0]);
         }
-        unset($lines[0]); // إزالة سطر التعريف من المعالجة
+        unset($lines[0]); 
+
+        // استخراج المسار الحالي لنظام الـ Routing
+        $requestedRoute = isset($_GET['route']) ? '/' . ltrim($_GET['route'], '/') : '/';
 
         try {
             $htmlBody = "";
@@ -73,30 +85,89 @@ class ThothEngine {
             $repeatBuffer = [];
             $repeatKey = "";
             $repeatIndent = 0;
+            
+            $isDefiningComponent = false;
+            $currentComponentName = "";
+            $componentIndent = 0;
 
             foreach ($lines as $index => $line) {
                 $this->currentLine = $index + 1;
                 $trimmed = trim($line);
                 
-                // تسريع معالجة الأسطر الفارغة والتعليقات باستخدام str_starts_with
                 if ($trimmed === "" || str_starts_with($trimmed, '#')) continue;
                 
                 $indent = strlen($line) - strlen(ltrim($line));
 
-                // Middleware Guard
+                // Guard System
                 if ($skipUntilIndent !== -1) {
                     if ($indent > $skipUntilIndent) continue;
                     else $skipUntilIndent = -1;
                 }
 
+                // --- 1. التنقل الذكي (Smart Routing) ---
+                if (str_starts_with($trimmed, 'Route "')) {
+                    preg_match('/Route "([^"]+)"/', $trimmed, $matches);
+                    $routePath = $matches[1] ?? '';
+                    if ($routePath !== $requestedRoute) {
+                        $skipUntilIndent = $indent; 
+                    }
+                    continue; 
+                }
+
+                // --- 2. Middleware ---
                 if (preg_match('/Auth="([^"]+)"/', $trimmed, $matches)) {
                     if (!$this->checkAuth($matches[1])) {
                         $skipUntilIndent = $indent;
                         continue;
                     }
                 }
+                
+                // --- 3. Sovereign Components ---
+                if ($isDefiningComponent) {
+                    if ($indent > $componentIndent) {
+                        $this->components[$currentComponentName][] = $line;
+                        continue;
+                    } else {
+                        $isDefiningComponent = false;
+                    }
+                }
+
+                if (str_starts_with($trimmed, 'Define ')) {
+                    $sep = $this->findSeparator($trimmed);
+                    if($sep === -1) throw new ThothSyntaxError("ComponentError: Missing ':' in Define statement.", $this->currentLine, $line);
+                    $currentComponentName = trim(substr($trimmed, 7, $sep - 7));
+                    $this->components[$currentComponentName] = [];
+                    $componentIndent = $indent;
+                    $isDefiningComponent = true;
+                    continue;
+                }
+
+                // --- 4. State Management ---
+                if (str_starts_with($trimmed, 'State ')) {
+                    $parts = explode(':', substr($trimmed, 6), 2);
+                    if (count($parts) === 2) {
+                        $stateKey = trim($parts[0]);
+                        $stateVal = trim($parts[1]);
+                        $this->stateVars[$stateKey] = $stateVal;
+                    } else {
+                        throw new ThothSyntaxError("StateError: Invalid State syntax. Expected 'State name: value'.", $this->currentLine, $line);
+                    }
+                    continue;
+                }
+
+                // --- 5. API Fetch Engine (الربط الخارجي السيادي) ---
+                if (str_starts_with($trimmed, 'API ')) {
+                    if (preg_match('/API\s+([a-zA-Z0-9_]+)="([^"]+)"/', $trimmed, $matches)) {
+                        $apiKey = $matches[1];
+                        $apiUrl = $matches[2];
+                        $this->fetchExternalApi($apiKey, $apiUrl, $this->currentLine, $line);
+                    } else {
+                        throw new ThothSyntaxError("APIError: Invalid API syntax. Expected 'API name=\"URL\"'.", $this->currentLine, $line);
+                    }
+                    continue;
+                }
 
-                // Repeat System
+                // --- 6. Repeat System ---
                 if ($isRepeatMode) {
                     if ($indent > $repeatIndent) { $repeatBuffer[] = $line; continue; }
                     else { $htmlBody .= $this->processRepeat($repeatKey, $repeatBuffer); $isRepeatMode = false; $repeatBuffer = []; }
@@ -109,7 +180,7 @@ class ThothEngine {
                     $repeatIndent = $indent; $isRepeatMode = true; continue;
                 }
 
-                // Components & Data
+                // --- 7. DataSource & Imports ---
                 if (str_starts_with($trimmed, 'DataSource:')) { $this->loadData(trim(substr($trimmed, 11))); continue; }
                 if (str_starts_with($trimmed, 'Var ')) { $this->parseVariable($trimmed); continue; }
                 if (str_starts_with($trimmed, 'Import:')) { 
@@ -121,24 +192,31 @@ class ThothEngine {
                 $line = $this->resolveDynamicData($line);
                 $trimmed = trim($line);
 
-                // Raw Injection (CSS/JS)
+                // --- 8. Raw Injection (CSS/JS) ---
                 if ($inRawMode) {
                     if ($indent <= $rawIndent && !empty($trimmed)) { $inRawMode = false; $htmlBody .= "</$rawType>\n"; }
                     else { $htmlBody .= $line . "\n"; continue; }
                 }
 
                 $sep = $this->findSeparator($trimmed);
-                if($sep === -1 && !empty($trimmed) && !isset($this->tagMap[explode(' ', $trimmed)[0]]) && !in_array(strtolower(explode(' ', $trimmed)[0]), $this->voidTags) && $cmd !== "StyleSheet" && $cmd !== "Scripting"){
-                    // الذكاء الاصطناعي لاكتشاف الأخطاء المطبعية
-                    throw new ThothSyntaxError("ParseError: Invalid syntax or missing separator ':'.", $this->currentLine, $line);
-                }
-
+                
                 $cmdPart = ($sep !== -1) ? trim(substr($trimmed, 0, $sep)) : $trimmed;
                 $val = ($sep !== -1) ? trim(substr($trimmed, $sep + 1)) : "";
 
                 $spacePos = strpos($cmdPart, ' ');
                 $cmd = ($spacePos !== false) ? substr($cmdPart, 0, $spacePos) : $cmdPart;
                 $attrs = ($spacePos !== false) ? trim(substr($cmdPart, $spacePos)) : "";
+                
+                // Component Instantiation
+                if (isset($this->components[$cmd])) {
+                    $componentHtml = $this->processComponent($cmd, $attrs, $indent);
+                    $htmlBody .= $componentHtml;
+                    continue;
+                }
+
+                if($sep === -1 && !empty($trimmed) && !isset($this->tagMap[explode(' ', $trimmed)[0]]) && !in_array(strtolower(explode(' ', $trimmed)[0]), $this->voidTags) && $cmd !== "StyleSheet" && $cmd !== "Scripting"){
+                    throw new ThothSyntaxError("ParseError: Invalid syntax or missing separator ':'. Unrecognized command or component '$cmd'.", $this->currentLine, $line);
+                }
 
                 if ($cmd === "StyleSheet" || $cmd === "Scripting") {
                     $inRawMode = true; $rawType = ($cmd === "StyleSheet") ? "style" : "script";
@@ -152,12 +230,38 @@ class ThothEngine {
                 }
 
                 $tag = isset($this->tagMap[$cmd]) ? $this->tagMap[$cmd] : strtolower($cmd);
+                
+                // --- 9. Layout Engine ---
+                $injectedStyle = "";
+                if ($cmd === 'Row') {
+                    $injectedStyle = "display:flex; flex-wrap:wrap;";
+                    if (preg_match('/gap="([^"]+)"/', $attrs, $m)) $injectedStyle .= " gap:{$m[1]};";
+                    if (preg_match('/align="([^"]+)"/', $attrs, $m)) $injectedStyle .= " align-items:{$m[1]};";
+                    $attrs = preg_replace('/(gap|align)="[^"]+"/', '', $attrs);
+                } elseif ($cmd === 'Column') {
+                    $injectedStyle = "display:flex; flex-direction:column;";
+                    if (preg_match('/width="([^"]+)"/', $attrs, $m)) $injectedStyle .= " flex:0 0 {$m[1]}; max-width:{$m[1]};";
+                    else $injectedStyle .= " flex:1;";
+                    $attrs = preg_replace('/width="[^"]+"/', '', $attrs);
+                }
+
                 $cleanAttrs = preg_replace('/Auth="[^"]+"/', '', $attrs);
-                $openingTag = "<$tag" . ($cleanAttrs ? " $cleanAttrs" : "") . ">";
+                $cleanAttrs = $this->injectStateBindings($tag, $cleanAttrs);
+                
+                if (!empty($injectedStyle)) {
+                    if (strpos($cleanAttrs, 'style="') !== false) {
+                        $cleanAttrs = preg_replace('/style="([^"]*)"/', 'style="$1 ' . $injectedStyle . '"', $cleanAttrs);
+                    } else {
+                        $cleanAttrs .= ' style="' . trim($injectedStyle) . '"';
+                    }
+                }
+
+                $openingTag = "<$tag" . ($cleanAttrs ? " " . trim($cleanAttrs) : "") . ">";
 
                 if (in_array($tag, $this->voidTags)) {
                     $htmlBody .= str_repeat(" ", $indent) . $openingTag . "\n";
                 } elseif ($val !== "") {
+                    $val = $this->injectStateText($val);
                     $htmlBody .= str_repeat(" ", $indent) . $openingTag . $val . "</$tag>\n";
                 } else {
                     $htmlBody .= str_repeat(" ", $indent) . $openingTag . "\n";
@@ -182,6 +286,31 @@ class ThothEngine {
         return (isset($_SESSION['user_role']) && $_SESSION['user_role'] === $role);
     }
 
+    /**
+     * دالة جلب البيانات من الـ APIs الخارجية
+     */
+    private function fetchExternalApi($key, $url, $lineNum, $lineContent) {
+        $options = [
+            'http' => [
+                'method' => 'GET',
+                'header' => "User-Agent: THOTH-Sovereign-Engine/12.0\r\n"
+            ]
+        ];
+        $context = stream_context_create($options);
+        $response = @file_get_contents($url, false, $context);
+        
+        if ($response === false) {
+            throw new ThothSyntaxError("APIError: Failed to fetch external data from '$url'.", $lineNum, $lineContent);
+        }
+        
+        $data = json_decode($response, true);
+        if ($data === null) {
+            throw new ThothSyntaxError("APIParseError: Received invalid JSON response from '$url'.", $lineNum, $lineContent);
+        }
+        
+        $this->dataContext[$key] = $data;
+    }
+
     private function processRepeat($key, $linesBuffer) {
         $dataArray = $this->dataContext[$key] ?? [];
         $output = "";
@@ -193,6 +322,54 @@ class ThothEngine {
         }
         return $output;
     }
+    
+    private function processComponent($componentName, $attrsStr, $baseIndent) {
+        $buffer = $this->components[$componentName];
+        $output = "";
+        preg_match_all('/([a-zA-Z0-9_]+)="([^"]+)"/', $attrsStr, $matches);
+        $props = [];
+        if(!empty($matches[1])) {
+            foreach($matches[1] as $idx => $propName) {
+                $props['@'.$propName] = $matches[2][$idx];
+            }
+        }
+
+        $subEngine = new ThothEngine();
+        $subEngine->dataContext = $this->dataContext;
+        $subEngine->variables = array_merge($this->variables, $props);
+        $subEngine->tagMap = $this->tagMap;
+        $subEngine->voidTags = $this->voidTags;
+        
+        $tempCode = "TYPE THOTH\n";
+        foreach($buffer as $l) {
+            $tempCode .= str_repeat(" ", $baseIndent) . $l . "\n";
+        }
+        
+        $tempFile = tempnam(sys_get_temp_dir(), 'thoth_comp_');
+        file_put_contents($tempFile, $tempCode);
+        $output = $subEngine->render($tempFile, true);
+        unlink($tempFile);
+        
+        return $output;
+    }
+
+    private function injectStateBindings($tag, $attrs) {
+        if (preg_match('/action="([^"]+)"/', $attrs, $match)) {
+            $action = $match[1]; 
+            $jsAction = "thothState.dispatch('{$action}')";
+            $attrs = preg_replace('/action="[^"]+"/', "onclick=\"{$jsAction}\"", $attrs);
+        }
+        return $attrs;
+    }
+
+    private function injectStateText($text) {
+        foreach ($this->stateVars as $key => $val) {
+            if (strpos($text, "@{{$key}}") !== false) {
+                $text = str_replace("@{{$key}}", "<span data-thoth-state='{$key}'>{$val}</span>", $text);
+            }
+        }
+        return $text;
+    }
 
     private function resolveDynamicData($text) {
         $text = str_replace(array_keys($this->variables), array_values($this->variables), $text);
@@ -227,10 +404,6 @@ class ThothEngine {
         return "<div style='font-family:sans-serif; background:#020617; color:#fff; height:100vh; display:flex; flex-direction:column; align-items:center; justify-content:center;'><h1>$title</h1><p style='color:#06b6d4'>$msg</p></div>";
     }
 
-    /**
-     * Python-Style Traceback Overlay
-     * تصميم هندسي ذكي يحدد الخطأ والمكان والملف بالتفصيل
-     */
     private function devErrorOverlay($msg, $line, $lineContent = "") {
         $escapedContent = htmlspecialchars($lineContent);
         return "
@@ -263,6 +436,32 @@ class ThothEngine {
         $title = $this->dataContext['site_title'] ?? "THOTH Compiled System";
         $desc = $this->dataContext['site_desc'] ?? "Architected by Abdelfatah Abdelhamed";
         
+        $stateJson = json_encode($this->stateVars);
+        $stateScript = "
+        <script>
+            // THOTH Frontend State Engine v12.0
+            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>";
+
         $liveReload = $this->devMode ? "<script>
             let lastMod = null;
             setInterval(async () => {
@@ -279,9 +478,9 @@ class ThothEngine {
                "    <meta charset='UTF-8'>\n" .
                "    <meta name='viewport' content='width=device-width, initial-scale=1.0'>\n" .
                "    <meta name='description' content='$desc'>\n" .
-               "    <meta name='generator' content='THOTH Sovereign Engine 11.0'>\n" .
+               "    <meta name='generator' content='THOTH Sovereign Engine 12.0.0'>\n" .
                "    <title>$title</title>\n" .
-               "</head>\n<body>\n$body\n$liveReload</body>\n</html>";
+               "</head>\n<body style=\"margin:0; font-family:sans-serif;\">\n$body\n$stateScript\n$liveReload</body>\n</html>";
     }
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "thoth-markup-lang",
-  "version": "11.0.0",
-  "description": "THOTH Sovereign Suite (Pulse Edition): A revolutionary indentation-based markup ecosystem featuring Strict File Identification (TYPE THOTH), Python-style tracebacks, recursive JSON data-binding, procedural middleware auth guards, and an ultra-high-performance runtime. Engineered by Engineer Abdelfatah Abdelhamed.",
+  "version": "12.0.1",
+  "description": "THOTH Sovereign Suite v12.0.0 (The Sovereign Cloud): The ultimate indentation-based reactive web engine. Features native API Fetch Engine, Smart Routing (SPA builder), Native Layouts (Flexbox), Sovereign Components, State Management, Python-style tracebacks, and an ultra-high-performance runtime. Engineered by Engineer Abdelfatah Abdelhamed.",
   "main": "thoth.js",
   "bin": {
     "thoth": "./thoth.js"
@@ -14,13 +14,26 @@
     "serve": "node thoth.js serve --port 3000 --strict",
     "validate": "node thoth.js validate --all",
     "auth-setup": "node thoth.js auth --init",
-    "version": "echo THOTH v11.0.0 Pulse Edition Sovereign Intelligence Suite"
+    "version": "echo THOTH v12.0.0 The Sovereign Cloud Intelligence Suite"
   },
   "keywords": [
     "thoth",
     "thoth-lang",
     "markup-language",
     "sovereign-engine",
+    "sovereign-cloud",
+    "api-fetch",
+    "data-fetching",
+    "rest-api",
+    "web-engine",
+    "smart-routing",
+    "spa-builder",
+    "layout-engine",
+    "flexbox-grid",
+    "core-framework",
+    "sovereign-components",
+    "state-management",
+    "reactive-ui",
     "pulse-edition",
     "python-style-traceback",
     "smart-error-handling",
@@ -59,4 +72,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/thoth.js

@@ -1,22 +1,28 @@
 #!/usr/bin/env node
 
 /**
- * THOTH Engine v11.0.0 - Pulse Edition (Sovereign Intelligence Suite)
+ * 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 والـ String manipulation.
+ * 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 {
@@ -36,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
 };
 
@@ -59,25 +65,38 @@ 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 v11.0.0 (Pulse) \x1b[0m');
+    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 + Traceback)');
+    console.log('   thoth serve [file].thoth    (Live SPA Server + Traceback)');
+}
+
+// --- محرك الاتصال الخارجي السيادي (متوافق مع كل نسخ 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);
+    });
 }
 
-/**
- * معالجة البيانات الديناميكية @{{key}} و @Variable (Fast Regex)
- */
 const DATA_REGEX = /@\{\{([^}]+)\}\}/g;
 function resolveData(text, context, variables = {}) {
     let resolved = text;
@@ -90,54 +109,138 @@ function resolveData(text, context, variables = {}) {
     });
 }
 
-/**
- * محرك التجميع المعماري (المسرع)
- */
-function compileThoth(inputPath, isDev = false) {
-    if (!fs.existsSync(inputPath)) {
-        throw new ThothSyntaxError(`Source Integrity Error: File not found.`, 0, "", inputPath);
+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;
+}
 
-    const source = fs.readFileSync(inputPath, 'utf8');
-    const lines = source.split(/\r?\n/);
+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 لدعم السحابة السيادية)
+ */
+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 ThothSyntaxError("Architectural Identity Error: Missing 'TYPE THOTH' protocol to ensure sovereignty.", 1, lines[0], inputPath);
+        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++) {
         const lineNum = i + 1;
         let line = lines[i];
         
-        // تسريع اكتشاف المسافات (أسرع من Regex search)
         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;
         }
 
+        // --- 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);
@@ -147,9 +250,10 @@ function compileThoth(inputPath, isDev = false) {
                 if(!Array.isArray(list)) {
                     throw new ThothSyntaxError(`DataMappingError: '${repeatScope.key}' is not a valid Array in Context.`, lineNum, line, inputPath);
                 }
-                list.forEach(item => {
-                    htmlContent += processBuffer(repeatScope.buffer, item, variables, inputPath, lineNum);
-                });
+                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 = [];
             }
@@ -164,15 +268,14 @@ function compileThoth(inputPath, isDev = false) {
             continue;
         }
 
-        // --- 3. Data Ingestion & Variables ---
+        // --- 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);
-            }
+            if (!fs.existsSync(dPath)) throw new ThothSyntaxError(`MissingDataError: DataSource '${jsonFileName}' not found.`, lineNum, line, inputPath);
             try {
-                dataContext = JSON.parse(fs.readFileSync(dPath, 'utf8'));
+                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);
             }
@@ -182,14 +285,23 @@ function compileThoth(inputPath, isDev = false) {
         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. Expected 'Var name: value'.`, lineNum, line, inputPath);
+            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;
@@ -200,7 +312,6 @@ function compileThoth(inputPath, isDev = false) {
             }
         }
 
-        // --- خوارزمية تحليل الفصل الذكي (Strict Parser) ---
         let colonIdx = -1;
         let inQuotes = false;
         for (let j = 0; j < processedTrimmed.length; j++) {
@@ -213,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;
@@ -223,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 += ' '.repeat(indent) + open + '\n';
         } else if (val) {
-            htmlContent += ' '.repeat(indent) + `${open}${val}</${tag}>\n`;
+            const finalVal = injectStateText(val, stateVars);
+            htmlContent += ' '.repeat(indent) + `${open}${finalVal}</${tag}>\n`;
         } else {
             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, inputPath, lines.length); });
+        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, filePath, baseLineNum) {
-    let res = "";
-    let bStack = [];
-    buffer.forEach((l, idx) => {
-        const ind = l.length - l.trimStart().length;
-        let pLine = resolveData(l, item, variables);
-        const t = pLine.trim();
-        let cIdx = t.indexOf(':'); // Fast path for loops
-        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 += ' '.repeat(ind) + op + '\n';
-        else if (valStr) res += ' '.repeat(ind) + `${op}${valStr}</${tag}>\n`;
-        else { res += ' '.repeat(ind) + 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 PULSE DEV MODE: ACTIVE ', 'background:#06b6d4;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 {
@@ -302,26 +473,24 @@ 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 v11.0.0">
+    <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:#020617; color:#f8fafc;">
+<body style="margin:0; background:#020617; color:#f8fafc; font-family:sans-serif;">
 ${content}
+${stateEngineScript}
 ${liveReload}
 </body>
-</html>`;
+</html>`};
 }
 
-/**
- * دالة توليد واجهة تتبع الأخطاء (Browser Overlay)
- */
 function getBrowserTracebackHTML(e) {
     if (e.name === 'ThothSyntaxError') {
         const escapedContent = e.lineContent.replace(/</g, '&lt;').replace(/>/g, '&gt;');
@@ -353,12 +522,9 @@ function getBrowserTracebackHTML(e) {
     </body>`;
 }
 
-/**
- * طباعة الأخطاء في التيرمينال
- */
 function printTerminalError(e) {
     if (e.name === 'ThothSyntaxError') {
-        console.error('\x1b[31m%s\x1b[0m', `\n⚠️  THOTH Traceback (most recent call last):`);
+        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', `    ^`);
@@ -370,14 +536,17 @@ function printTerminalError(e) {
 
 // --- طبقة التنفيذ ---
 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);
@@ -386,20 +555,25 @@ if (command === 'serve') {
         }
     });
 
-    server.listen(config.port, () => {
+    server.listen(globalConfig.port, () => {
         console.log('\x1b[36m%s\x1b[0m', `──────────────────────────────────────────`);
-        console.log(` ✔ SERVER ACTIVE: http://localhost:${config.port}`);
+        console.log(` ✔ SERVER ACTIVE: http://localhost:${globalConfig.port}`);
         console.log(` ✔ ARCHITECTURE: ${target}`);
-        console.log(` ✔ MODE: Pulse Edition v11.0.0`);
+        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) {
-        printTerminalError(e);
-        process.exit(1);
-    }
+     displayUsage();
 }