وثائق المطورين

1. المعمارية العامة

نبراس شِل مبني على طبقات متدرجة، كل طبقة تخدم هدفاً محدداً:

┌────────────────────────────────────────────────────────┐ │ Layer 1: shell.qml (Entry Point) │ │ ├── SplashScreen → ThemeManager → Main UI │ │ └── Variants (per-screen) + Singletons (global) │ ├────────────────────────────────────────────────────────┤ │ Layer 2: Bars & Windows │ │ ├── Topbar, LeftBar (Layer Shell panels) │ │ └── LeftWindow, Dock, Settings (Popup windows) │ ├────────────────────────────────────────────────────────┤ │ Layer 3: Services (Singletons) │ │ ├── Hardware: Audio, Brightness, HardwareState │ │ ├── Data: Weather, Music, Network, Clipboard, Todo │ │ ├── AI: AiService → AiTask → Analysis Pipeline │ │ └── UI: Overlay, Icon, NotifManager │ ├────────────────────────────────────────────────────────┤ │ Layer 4: Scripts (Python/Bash) │ │ └── venv: ~/.cache/nibrasshell/venv │ └────────────────────────────────────────────────────────┘

أنماط التصميم الأساسية

Singleton-heavy: الخدمات الأساسية تستخدم pragma Singleton للوصول العام.
EventBus pub/sub: التواصل بين المكونات عبر أحداث مسماة في EventNames.js.
Theme-reactive: كل مكونات UI مرتبطة بخصائص ThemeManager.selectedTheme فتتحدث تلقائياً.
Per-screen vs Global: الأشرطة تُنشأ لكل شاشة (Variants)، النوافذ المنبثقة نسخة واحدة.
Lazy loading: القوائم تُحمّل عند الطلب عبر StackView لتوفير الموارد.

2. نقطة البداية

المكوّن الرئيسي في:

config/quickshell/shell.qml

هذا الملف يجمع الطبقات الأساسية ويدير تسلسل الإقلاع:

SplashScreen: شاشة بدء متحركة.
ThemeManager.initialThemeReady: إشارة لبدء تحميل الواجهة.
Loader (async): تحميل غير متزامن مع تأثير opacity.
Variants: إنشاء نسخة لكل شاشة من Desktop, Topbar, LeftBar, SmartCapsule, Dock.

التحكم الخارجي (IPC)

يمكن التحكم بالقائمة من سكربتات خارجية عبر:

quickshell ipc call LeftBar toggleDashboardMenu # Dashboard quickshell ipc call LeftBar toggleNotificationsMenu # Notifications quickshell ipc call LeftBar toggleWeatherMenu # Weather quickshell ipc call LeftBar toggleMonitoringMenu # Monitoring quickshell ipc call LeftBar toggleNetworkingMenu # Network quickshell ipc call LeftBar toggleClipboardMenu # Clipboard quickshell ipc call LeftBar toggleTodoMenu # Todo quickshell ipc call LeftBar toggleAiMenu # AI Chat quickshell ipc call LeftBar toggleApplauncherMenu # App Launcher quickshell ipc call LeftBar togglePowerMenu # Power Menu quickshell ipc call LeftBar toggleDock # Dock

3. إدارة الإعدادات

ConfigStore.qml: يقرأ/يكتب ~/.nibrasshell.json عبر FileView مع مراقبة الملف.
App.qml: يوحّد المسارات (assets, scripts, cache)، أوامر Python/Bash، وإعدادات AI.
الكاش: ~/.cache/nibrasshell/ يحتوي theme.json و venv.
EventBus.qml: نظام pub/sub مع emit(), on(), off(), clearOwner().
ConstValues.js: ثوابت القوائم (0-9)، حالات الكبسولة، أولوياتها.

4. محرك الثيمات

نظام ثيمات متعدد الطبقات مع تكامل عميق مع النظام.

ThemeManager - 6 مراحل تحميل

1. Request → طلب الثيم (من المستخدم أو افتراضي) 2. Cache check → فحص ~/.cache/nibrasshell/theme.json 3. Loader instruct → توجيه ThemeLoader لتحميل QML 4. Object creation → إنشاء كائن الثيم 5. Cache hydration → ملء الخصائص من الكاش 6. System apply → تطبيق الثيم على النظام (SystemBridge)

BaseTheme - 100+ خاصية

colors: M3 palette (primary, secondary, tertiary, surface, error, outline...)
dimensions: radii, bar sizes, component sizes, M3 shape scale.
typography: fonts, sizes.
systemSettings: Qt style, Kvantum, GTK, Plasma, Konsole, icons, cursor.
hyprlandConfiguration: borders, gaps, layout, animations, blur, shadows.
desktopClock: position, format, depth effect.

SystemBridge - التكامل مع النظام

يطبق الثيم على أدوات التوزيعات المختلفة:

Plasma: colorscheme, icons, font, cursor.
GTK3/4: theme, icons, font, cursor.
Kvantum: Qt application styling.
Konsole: terminal profiles.
Hyprland: borders, gaps, animations via config rewrite.

14 ثيم: Catppuccin, Colors, Deer, Dracula, Gruvbox, M3, Nord, TokyoNight (كل منها Dark + Light).

5. الخدمات الأساسية

الخدمات مقسمة إلى طبقات حسب الوظيفة:

Hardware Layer

الخدمة	الدور
Audio	PipeWire volume/mute control
Brightness	DDC/CI (external) + brightnessctl (laptop)
HardwareState	Aggregator: volume, brightness, battery, keyboard layout

Data Layer

الخدمة	الدور
Weather	wttr.in API + AI analysis + smart polling + 8 alert signals
MusicService	MPRIS + AI commentary + history (20 tracks) + debounced analysis
NetworkService	WiFi scan/connect + data usage (monthly/daily/live/history)
ClipboardService	wl-paste watch + Python clipboard manager + smart model sync
TodoService	Persistent JSON + AI prioritization + due tracking + notifications

AI Layer

الخدمة	الدور
AiService	Priority queue (0-2) + rate limiting (3s cooldown, 15s throttle) + JSON cleaning
AiTask	Individual process execution unit (spawned per request)
AiAnalysisService	Orchestrator: SystemService signals → SpikeDetector → EventStore

Analysis Layer

الخدمة	الدور
SpikeDetector	CPU/RAM/Temp spike detection + AI triggers (priority 2)
CooldownManager	3-level cooldown (global 30s, per-process 30s, temp 5min)
EventStore	In-memory event log (max 50) with AI results
DiagnosticsCollector	Normalized data collection for processes/temps

UI Support

الخدمة	الدور
NotifManager	Notification server + DND + sound dispatch + auto-cleanup
OverlayService	Fullscreen overlay (image preview mode)
IconService	Batch icon resolution + theme-aware caching + flicker prevention
ActionResponses	Pre-generated AI messages (round-robin rotation per category)

System Facade

الخدمة	الدور
SystemService	Aggregator: BootAnalyzer + HardwareState + ResourceMonitor + ActionResponses
ResourceMonitor	CPU/RAM/Temp monitoring + episode-based alerting + hysteresis
ResourceDiagnostics	On-demand process/temp diagnostics with request deduplication
BootAnalyzer	AI-powered boot log analysis + solution suggestions

6. نظام الذكاء الاصطناعي

نظام AI متكامل مع طابور أولويات وحماية من الإغراق.

AiService - البوابة المركزية

AiService: ├── Priority Queue: 0=Low, 1=Normal, 2=High ├── Rate Limiting: 3s cooldown + 15s per-requestId throttle ├── Deduplication: same requestId within throttle → dropped └── JSON Cleaning: strips markdown fences, validates fields

Spike Detection Pipeline

ResourceMonitor (signals) ↓ SpikeDetector → CooldownManager (check) ↓ (if allowed) EventStore (create event with "Analyzing...") ↓ AiService (priority 2 - High) ↓ AI Analysis → EventStore.applySpikeAnalysis ↓ UI updates with: aiTitle, aiNarrative, aiRootCause, aiConfidence, aiActions

ActionResponses - رسائل تفاعلية

Categories: charging, discharging, cpu_alerts, ram_alerts, temp_alerts.
Round-robin: كل تنبيه يعرض رسالة مختلفة من المصفوفة.
Auto-fetch: يجلب الرسائل بعد 5 ثوانٍ من بدء التشغيل.

7. الكبسولة الذكية

Widget مستوحى من Dynamic Island مع تعبيرات عين متحركة.

SmartCapsule.qml (PanelWindow): ├── IdleBar: compact state (always visible) └── ExpandedCard: detailed state (on hover/click) logic/: ├── CapsuleCoordinator: priority-based content │ └── IDLE(0) → NORMAL(1) → HIGH(2) → CRITICAL(5) ├── CapsuleManager: state transitions ├── EyeController: 10 animated shapes │ ├── NormalEye, HappyEye, SadEye, SleepingEye │ ├── ThinkingEye, FocusedEye, HeartEye, DeadEye │ ├── ListeningEye, Brow └── HoverResponseManager: hover interactions

8. الأشرطة والنوافذ

Bars (Layer Shell)

Topbar: SystemTray | NetworkSpeed | ActiveWindow | Clock | Monitors
LeftBar: 10 icon buttons (Dashboard, Notifications, Weather, Monitoring, Network, Clipboard, Todo, AI, Apps, Power)

Windows (Popup)

LeftWindowFull: StackView-based menu system (3 styles: FLOATING, DOCKED_FIXED_BAR, DOCKED_MOVING_BAR)
BottomLauncher: app launcher with command mode (> prefix)
Dock: pinned apps with auto-hide
Settings: ApplicationWindow with General/Appearance/Monitors/Audio sections
PowerMenuWindow: shutdown/reboot/logout/suspend/lock
Cheatsheet: keyboard shortcuts reference
OverlayWindow: fullscreen overlay layer

9. نظام الأحداث

EventBus (pub/sub)

EventBus: ├── emit(eventName, data) → بث حدث ├── on(eventName, callback) → اشتراك ├── off(eventName, callback) → إلغاء اشتراك └── clearOwner(owner) → تنظيف تلقائي عند تدمير الكائن

EventNames.js - أمثلة

OPEN_SETTINGS, OPEN_LEFTBAR, CLOSE_LEFTBAR TOGGLE_BOTTOM_LAUNCHER, TOGGLE_DOCK, TOGGLE_POWER_MENU CPU_THRESHOLD_EXCEEDED, MEMORY_THRESHOLD_EXCEEDED TEMPERATURE_THRESHOLD_EXCEEDED, WEATHER_UPDATED

10. التكامل مع Python

Python يعمل في بيئة معزولة: ~/.cache/nibrasshell/venv/bin/python

🤖 AI Scripts

ai/main.py - main AI gateway
ai/list-gemini.py - model listing

📊 Monitoring

system_monitor.py - continuous CPU/RAM/Temp
system_diagnostics.py - on-demand
battery_info.py

🌐 Network

network/list_wifi.py
network/connect_wifi.py
network/data_usage.py (vnstat)
network/live_usage.py (nethogs)

🎨 Theme Integration

resolve_theme_icons.py
list_qt_styles.py, list_icon_themes.py
list_plasma_schemes.py
list_kvantum_themes.py
list_gtk_themes.py

🖼️ Wallpaper/Depth

m3/dynamic-m3.py - Material You colors
scan_wallpapers.py
create_depth_image_rembg.py
create_depth_image_opencv.py

🔧 Utilities

get_clipboard.py
apply_konsole_profile_open_sessions.py

11. السكربتات المهمة

Python

monitoring: system_monitor.py, system_diagnostics.py
wallpapers: scan_wallpapers.py, dynamic-m3.py
depth: create_depth_image_rembg.py
network: list_wifi.py, connect_wifi.py, data_usage.py
ai: main.py, list-gemini.py

Bash

internet.sh - فحص الاتصال
temp.sh - قراءة الحرارة
get_wallpapers.sh - جلب الخلفيات

12. التشغيل والتصحيح

تشغيل Quickshell

config/quickshell/run.fish

السكربت يضبط log rules لتقليل الضوضاء:

qs -p <shell_dir> --log-rules "..." # Suppresses: DBus errors, notification warnings, SNI warnings

نصائح التصحيح

اختبار AI: AiAnalysisService.testHighCpu / testHighRam
فحص الأحداث: EventStore.eventsModel (آخر 50 حدث)
كاش الثيم: ~/.cache/nibrasshell/theme.json
الإعدادات: ~/.nibrasshell.json
ملفات التشغيل: ~/.cache/nibrasshell/venv/

ملاحظات تطوير

الكبسولة الذكية في config/quickshell/windows/smart_capsule.
القائمة الجانبية في config/quickshell/windows/leftwindow.
الإعدادات في config/quickshell/windows/settings.
المكونات القابلة لإعادة الاستخدام في components/.
الأدوات المساعدة في utils/Helper.qml و utils/helpers.js.