steganopixel/CUSTOMIZATION_GUIDE.md

دليل التخصيص وإدارة الإضافات (Customization & Asset Guide)

يوفر هذا الدليل شرحاً تفصيلياً لجميع الإضافات (Assets)، الخطوط، الألوان، والمكتبات المستخدمة في SteganoPixel، مع تعليمات خطوة بخطوة للمطورين حول كيفية تعديلها أو استبدالها وتصحيح المشاكل المحتملة.

---

1. الإضافات المستخدمة (Assets Inventory)

أ. الصور والأيقونات (Images & Icons)

• المسار الدقيق: public/ (للملفات الثابتة) وداخل كود src/App.tsx (أيقونات متجهات SVG المدمجة).
• الغرض منها: تعزيز التجربة البصرية التفاعلية (أيقونات السحب والإفلات، علامات النجاح، ومؤشرات التنزيل).
• كيفية التعديل أو الاستبدال:
  • لاستبدال أيقونات الواجهة، ابحث عن وسوم <svg> في src/App.tsx واستبدلها بأي كود SVG مفضل (مثلاً من Lucide أو Heroicons).
  • لإضافة شعار ثابت، ضع ملف الصورة (مثلاً logo.png) في مجلد public/ واستدعه في الكود عبر <img src="/logo.png" alt="Logo" />.
• تصحيح المشاكل:
  • مشكلة: الأيقونة تظهر بحجم ضخم أو مشوه.
  • الحل: تأكد من تحديد خصائص العرض والطول في أصناف Tailwind (مثلاً h-6 w-6)، وتأكد من وجود خاصية fill="none" و stroke="currentColor" في وسم الـ SVG الأساسي.

ب. الخطوط (Fonts & Typography)

• المسار الدقيق: معرّفة في src/index.css (:root { font-family: ... }) ويتم الاعتماد على الخطوط القياسية ومكتبة Inter.
• الغرض منها: تأمين قراءة ممتازة ومريحة للنصوص والتعليمات باللغتين العربية والإنجليزية.
• كيفية تغيير الخطوط (عناوين، نصوص أساسية، أكواد):
  1. افتح ملف src/index.css.
  2. لتغيير خط العناوين والنصوص الأساسية، قم باستيراد خطك المفضل من Google Fonts (مثلاً Cairo أو Tajawal) في رأس الملف:

     @import url('https://fonts.googleapis.com/css2?family=Tajawal:wght@400;700;900&display=swap');
     
     :root {
       font-family: 'Tajawal', system-ui, -apple-system, sans-serif;
     }
     

  3. لتخصيص خط الأكواد والنصوص المستخرجة (Monospace)، أضف تعريفاً خاصاً لعناصر <textarea>:

     textarea {
       font-family: 'Fira Code', 'Courier New', monospace;
     }
     

• تصحيح المشاكل:
  • مشكلة: الخط العربي يظهر متقطعاً أو أوزانه (Bold/Regular) لا تعمل بشكل صحيح.
  • الحل: تأكد من تضمين جميع الأوزان المطلوبة في رابط الاستيراد (wght@400;600;800)، وتأكد من عدم وجود أخطاء إملائية في اسم عائلة الخط داخل :root.

جـ. الألوان والثيمات (Colors & Theming System)

• المسار الدقيق: معرّفة كفئات ذريّة (Utility Classes) في src/App.tsx و كمتغيرات في src/index.css.
• الغرض منها: تحديد الهوية البصرية للتطبيق (اللون البنفسجي، الخلفيات الزجاجية، والتنبيهات).
• كيفية تعديل الألوان والثيمات:
  • تغيير اللون الأساسي (Primary Theme): التطبيق يستخدم حالياً فئات violet-500 حتى violet-700 و indigo-600. لتحويل ثيم التطبيق إلى الأزرق الملكي (Blue Theme) مثلاً، استبدل كل:
    • from-violet-500 to-indigo-600 ➔ from-blue-500 to-cyan-600
    • bg-violet-600 hover hover:bg-violet-700 ➔ bg-blue-600 hover hover:bg-blue-700
    • text-violet-700 ➔ text-blue-700
  • تعديل خلفية التدرج العامة: افتح src/App.tsx وعدل حاوية الصفحة الجذرية:

    // من البنفسجي إلى الأبيض:
    bg-[radial-gradient(circle_at_top,_rgba(124,58,237,0.16),_transparent_34%),linear-gradient(180deg,_#f8fafc,_#eef2ff_45%,_#ffffff)]
    
    // لتحويله إلى ثيم رمادي داكن (Dark Theme):
    bg-[radial-gradient(circle_at_top,_rgba(30,41,59,0.5),_transparent_34%),linear-gradient(180deg,_#0f172a,_#1e293b_45%,_#0f172a)] text-slate-100
    

• تصحيح المشاكل:
  • مشكلة: التدرج اللوني لا يظهر أو يظهر كخلفية بيضاء صلبة.
  • الحل: تأكد من عدم وجود مسافات فارغة غير مسموح بها داخل الأقواس المعقوفة في Tailwind bg-[...] (استخدم الشرطة السفلية _ بدلاً من المسافة).

د. المكتبات الخارجية (Third-Party Libraries)

• المكتبات المستخدمة:
  1. react (v18.3.1): مكتبة الواجهات.
  2. react-dom (v18.3.1): مشغل React على المتصفح.
  3. tailwindcss (v4.0.0): إطار عمل الأنماط.
• المسار الدقيق: package.json.
• كيفية التعديل أو التحديث: لتحديث المكتبات إلى أحدث إصدار، نفذ الأمر التالي في موجه الأوامر:

  npm update
  

  أو لتثبيت مكتبة إضافية (مثلاً canvas-confetti للاحتفال عند نجاح الاستخراج):

  npm install canvas-confetti
  npm install -D @types/canvas-confetti
  

• تصحيح المشاكل:
  • مشكلة: ظهور تعارض في الحزم بعد التحديث (Peer Dependencies Conflict).
  • الحل: احذف مجلد node_modules وملف package-lock.json ثم أعد التثبيت النظيف عبر npm install.

---

2. تخصيص المكونات التفاعلية (Components Customization)

تخصيص بطاقة الرفع (UploadCard)

إذا أردت تغيير السلوك ليقبل ملفات PDF أو نصوص، يمكنك تعديل خاصية accept داخل مكون UploadCard في src/App.tsx:

// الوضع الحالي (صور فقط):
<input id={inputId} type="file" accept="image/*" className="hidden" onChange={handleChange} />

// لتفعيل قبول الصور والوثائق:
<input id={inputId} type="file" accept="image/*,.pdf,.docx" className="hidden" onChange={handleChange} />

تخصيص بطاقة التنزيل (DownloadCard)

لتعديل اسم الملف الافتراضي عند التنزيل، ابحث عن استدعاء setEncodedAsset في دالة handleEncode:

setEncodedAsset({
  url,
  // يمكنك تغيير اللاحقة "-hidden" إلى أي عبارة أخرى:
  fileName: `${baseName(encodeImage.file.name)}-secret-data.png`,
  size: blob.size,
  width: canvas.width,
  height: canvas.height,
});