kreftjs 0.0.17-beta → 0.0.20-beta

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,234 @@
1
+ # الفصل التاسع: الاختبار والبناء والنشر
2
+
3
+ ## اختبار الواجهة الخلفية
4
+
5
+ تُختبر شيفرة الخادم بمشغّل الاختبارات المدمج في Node وقاعدة SQLite في الذاكرة، فالاختبارات سريعة ولا تمس بياناتك الحقيقية.
6
+
7
+ ```json
8
+ {
9
+ "scripts": { "test": "node --test \"tests/**/*.test.js\"" }
10
+ }
11
+ ```
12
+
13
+ ```js
14
+ // tests/models/post.test.js
15
+ const test = require('node:test')
16
+ const assert = require('node:assert/strict')
17
+ const { createSchema, setConnection } = require('kreftjs/server')
18
+ const { connect } = require('kreft/bin/db.js')
19
+ const Post = require('../../backend/app/Models/Post')
20
+
21
+ test.before(async () => {
22
+ const db = await connect('sqlite::memory:') // قاعدة فارغة جديدة لهذا الملف
23
+ setConnection(db)
24
+ await createSchema(db).create('posts', (table) => {
25
+ table.id()
26
+ table.string('title')
27
+ table.timestamps()
28
+ })
29
+ })
30
+
31
+ test('a post can be created and found', async () => {
32
+ const post = await Post.create({ title: 'Hello' })
33
+ assert.equal((await Post.find(post.id)).title, 'Hello')
34
+ })
35
+ ```
36
+
37
+ لاختبار جداول مشروع كامل شغّل ترحيلاته الحقيقية بدل بناء المخطط يدويًا: `migrator.migrate(db, 'backend/database/migrations')`.
38
+
39
+ اختبارات المكوّنات للمتصفح تعيش في `frontend/tests/` وتُفتح بـ `kreft dev`.
40
+
41
+ ## الأدوات المرافقة للتطوير
42
+
43
+ كل ما هنا يأتي مع Kreft:
44
+
45
+ **إعادة التحميل الفورية.** أثناء `kreft dev` احفظ ملف `.kreft` فيُبدَّل ذلك المكوّن وحده وتبقى حالته. وملف `.css` يُعاد تحميله بلا تحديث للصفحة، والخطأ يعرض طبقة فيها الملف والسطر.
46
+
47
+ **أدوات Kreft (DevTools).** زر **S** في الزاوية (أو <kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>) يفتح لوحة:
48
+
49
+ | التبويب | يعرض |
50
+ |---|---|
51
+ | Components | الشجرة الحية. اختر مكوّنًا لترى الخصائص والحالة والقيم المشتقة، وغيّر الحالة هناك. |
52
+ | Stores | قيم كل مخزن (قابلة للتغيير) و`$reset()`. |
53
+ | Route | المسار الحالي وكل المسارات، مع زر للذهاب إليها. |
54
+ | Timeline | أفعال المخازن ورسائل الـ bus حال وقوعها. |
55
+
56
+ الزر واللوحة موجودان تحت `kreft dev` فقط؛ التطبيقات المبنية لا تحتويهما أبدًا.
57
+
58
+ ### مراقب الأخطاء
59
+
60
+ في التطوير، خطأ غير ملتقط على الخادم يعرض صفحة تفاعلية بدل رسالة مجردة: مستكشف مكدّس يخفي إطارات المكتبات ويبرز إطاراتك، ومعاينة للشيفرة حول السطر الفاشل، ومحرك اقتراحات للأخطاء الشائعة (خطأ إملائي في دالة نموذج، أو قراءة خاصية من `undefined`، أو جدول مفقود يحتاج `kreft migrate`)، والطلب كاملًا (مع إخفاء كلمات المرور والرموز والكوكيز). وتظهر الصفحة فقط حين `APP_ENV` ليس `production` و`APP_DEBUG` صحيح. **في الإنتاج الخطأ نفسه يجيب `Server error.` ببساطة**، بلا مكدّس أو أسماء ملفات.
61
+
62
+ ## البناء (Build)
63
+
64
+ ```bash
65
+ npm run build # أو: kreft build
66
+ npm run preview # افحص النتيجة: kreft dev dist
67
+ ```
68
+
69
+ | الملف | ما هو |
70
+ |---|---|
71
+ | `index.html` | صفحتك، تحمّل الآن الملفات أدناه. |
72
+ | `kreftjs.js` | الإطار. |
73
+ | `app.js` | كل ملفات `.kreft`، مصرّفة. |
74
+ | `app.css` | كل كتل `<style>`؛ المحصورة محصورة فعلًا. |
75
+ | `main.js` | شيفرة `<script>` المضمنة في `index.html`. |
76
+ | `deps/` و`vendor/` | حزم npm وملفات CSS التي تستوردها ملفاتك، مصغّرة. |
77
+
78
+ ماذا تكسب:
79
+
80
+ - **أول تحميل أسرع:** يحمّل المتصفح `app.js` واحدًا ولا يصرّف شيئًا.
81
+ - **سياسة CSP صارمة تعمل:** كل تعبير يصير دالة حقيقية، فلا `eval` ولا `new Function` في التطبيق المبني.
82
+ - **أخطاء قبل النشر:** أي خطأ في أي ملف `.kreft` يوقف البناء ويسمي الملف والسطر.
83
+
84
+ خيارات: `kreft build ./site --out public` يبني مجلدًا آخر، و`--base /` يغيّر `<base href>`. و`--no-htaccess` يتخطى ملف `.htaccess`.
85
+
86
+ ### القاعدة (base) الصحيحة: خطأ شائع جدًا
87
+
88
+ يحتفظ البناء بوسم `<base href="…">` المكتوب في `index.html` المصدر، ويضبط قواعد `.htaccess` عليه. **إن كان `index.html` المصدر يحمل قاعدة مجلد فرعي** (مثل `<base href="/demo/">` في مشروع `demo`) وأنت ترفع الموقع إلى الجذر، فالنتيجة **صفحة بيضاء**: المتصفح يطلب `/demo/app.js` فلا يجد شيئًا.
89
+
90
+ الحل: اذكر القاعدة صراحة عند البناء للنشر في الجذر:
91
+
92
+ ```bash
93
+ kreft build --out dist/site --base /
94
+ ```
95
+
96
+ وافحص `index.html` المبني: يجب أن ترى `<base href="/">`. وإن كان موقعك في مجلد فرعي `/blog/` فابنِ بـ `--base /blog/`.
97
+
98
+ ### الرفع إلى استضافة
99
+
100
+ **استضافة ثابتة: Hostinger وcPanel وأي استضافة Apache.** ارفع ما **داخل** `dist/` (لا المجلد نفسه) إلى المجلد الذي يخدم الموقع، وهو عادة `public_html`. في hPanel من Hostinger: **Files ← File Manager ← public_html ← Upload**، أو استعمل FTP. لا تستعمل مستورِدات "framework" أو "Node.js app" لهذا: فهي تبحث عن `package.json` وتقول *Unsupported framework or invalid project structure* لأن `dist/` فيه ملفات منتهية فقط.
101
+
102
+ ويكتب `kreft build` ملف `dist/.htaccess`:
103
+
104
+ ```apache
105
+ RewriteEngine On
106
+ RewriteBase /
107
+ RewriteRule ^index\.html$ - [L]
108
+ RewriteCond %{REQUEST_FILENAME} !-f
109
+ RewriteCond %{REQUEST_FILENAME}/index.html !-f
110
+ RewriteCond %{REQUEST_URI} !^/api/
111
+ RewriteCond %{REQUEST_URI} !\.[A-Za-z0-9]+$
112
+ RewriteRule . /index.html [L]
113
+ ```
114
+
115
+ Apache لا يعرف إلا الملفات الموجودة على القرص، فبدون هذه القواعد يعطي `/docs` أو أي عنوان نظيف خطأ 404 عند فتحه أو إعادة تحميله. ومعها، كل عنوان صفحة (بلا امتداد وليس تحت `/api/`) ليس ملفًا حقيقيًا يفتح `index.html` ويتولى الموجِّه الباقي. ارفع الملف أيضًا (يبدأ بنقطة فبعض مديري الملفات يخفونه؛ فعّل "show hidden files").
116
+
117
+ ويضع `kreft build` أيضًا بصمة قصيرة في عنوان كل سكربت وملف أنماط (`app.js?v=28a965f6`)، ويطلب `.htaccess` من الاستضافة ألا تحتفظ بـ `index.html`. الاستضافات تخزّن `.js` و`.css` أيامًا، فبدون البصمة يظل الزوار يشغّلون الإطار والصفحات القديمة بعد رفع بناء جديد.
118
+
119
+ > **ملاحظة:** هذا يستضيف الواجهة الأمامية فقط. تسجيل الدخول وقاعدة البيانات وكل ما تحت `/api` يحتاج خادم Node.js الذي لا يشغّله Apache.
120
+
121
+ **خطة Node.js أو VPS.** ارفع المشروع كله (بلا `node_modules`)، لا `dist/`. أضف Kreft إلى اعتماداتك بـ `npm i kreftjs`، وابنِ بـ `npm run build`، وشغّل الخادم بـ `npm run serve` (يقرأ `PORT` الذي تضبطه استضافتك). سكربت `start` المولَّد يشغّل خادم التطوير فلا تستعمله في الإنتاج.
122
+
123
+ على VPS أبقِه يعمل بـ PM2 وضع nginx أمامه للنطاق وHTTPS:
124
+
125
+ ```bash
126
+ npm install && npm run build
127
+ npm i -g pm2
128
+ pm2 start "npm run serve" --name my-app && pm2 save
129
+ ```
130
+
131
+ ```nginx
132
+ server {
133
+ server_name example.com;
134
+ location / {
135
+ proxy_pass http://127.0.0.1:8000;
136
+ proxy_set_header Host $host;
137
+ proxy_set_header X-Forwarded-Proto $scheme;
138
+ }
139
+ }
140
+ ```
141
+
142
+ ثم `sudo certbot --nginx -d example.com` يضيف HTTPS. اضبط `APP_ENV=production` و`APP_KEY` حقيقيًا في `.env` أولًا، وراجع [قائمة الفحص](07-auth-and-security.md).
143
+
144
+ ## تحسين محركات البحث (SEO)
145
+
146
+ ### صفحات HTML جاهزة: `--prerender`
147
+
148
+ ```bash
149
+ npm i -D jsdom # مرة لكل مشروع
150
+ kreft build --prerender # كل مسار بلا :params
151
+ kreft build --prerender /users/1,/users/2 # وهذه العناوين أيضًا
152
+ ```
153
+
154
+ كل صفحة تُفتح في متصفح محاكى، وتُحمَّل بياناتها، وتُحفظ النتيجة في `dist/<page>/index.html`، فيحصل الزوار ومحركات البحث على HTML منتهٍ.
155
+
156
+ الوسوم التي تضعها الصفحة بـ `.seo({...})` أو `meta` (الوصف، وcanonical، وOpen Graph، وTwitter، وhreflang، وJSON-LD، و`lang` و`dir`) تُحفظ في HTML الصفحة أيضًا، فتراها معاينات الروابط والزواحف التي لا تشغّل JavaScript.
157
+
158
+ ### SEO لصفحات تأتي من قاعدة بياناتك: `backend/routes/seo.js`
159
+
160
+ ```js
161
+ // backend/routes/seo.js
162
+ const Post = require('../app/Models/Post')
163
+
164
+ module.exports = {
165
+ '/': { title: 'متجري', description: 'كل ما يحتاجه البيت' },
166
+ '/blog/:slug': async ({ slug }) => {
167
+ const post = await Post.query().published().where('slug', slug).first()
168
+ if (!post) return null // 404 حقيقي مع noindex
169
+ return {
170
+ title: post.title,
171
+ description: String(post.body || '').slice(0, 150),
172
+ schema: { '@type': 'Article', headline: post.title },
173
+ }
174
+ },
175
+ // عناوين صفحات بياناتك، لـ `kreft sitemap`
176
+ urls: async () => (await Post.query().published().get()).map((p) => ({ path: '/blog/' + p.slug, lastmod: p.updated_at })),
177
+ }
178
+ ```
179
+
180
+ `kreft dev` و`kreft serve` يجيبان طلب الصفحة بـ `index.html` مع وسوم أول عنوان مطابق. واضبط `APP_URL` لتحصل كل صفحة على `canonical`.
181
+
182
+ ### صفحات كاملة للزواحف
183
+
184
+ الزاحف أو معاينة الرابط (Googlebot وBingbot وWhatsApp وFacebook وX وTelegram …) الذي لا يشغّل JavaScript سيرى `<div id="app">` فارغًا. لهؤلاء يفتح `kreft dev` و`kreft serve` الصفحة في المتصفح المحاكى نفسه، وينتظر تحميل بياناتها، ويجيب بالصفحة مرسومة.
185
+
186
+ ```bash
187
+ npm i -D jsdom # مرة لكل مشروع
188
+ KREFT_SSR=bots # الافتراضي: الزواحف ومعاينات الروابط فقط
189
+ KREFT_SSR=all # كل زائر
190
+ KREFT_SSR=off # أبدًا
191
+ KREFT_SSR_TTL=300 # ثوانٍ تحتفظ فيها بالصفحة المرسومة
192
+ ```
193
+
194
+ ### خريطة الموقع وrobots.txt
195
+
196
+ ```bash
197
+ kreft sitemap --url https://example.com # public/sitemap.xml و public/robots.txt
198
+ kreft sitemap --url https://example.com --urls urls.js # مع العناوين في ذلك الملف
199
+ ```
200
+
201
+ ## نشر الواجهة الخلفية
202
+
203
+ ```bash
204
+ NODE_ENV=production kreft serve dist
205
+ ```
206
+
207
+ وقبلها أنجز [قائمة الفحص قبل الإنتاج](07-auth-and-security.md).
208
+
209
+ ## TypeScript
210
+
211
+ يعمل TypeScript في المتصفح (ملفات `.kreft` ووحدات `.ts`) وعلى الخادم (`routes/api.ts` و`app/**/*.ts` والترحيلات والبذور).
212
+
213
+ ```bash
214
+ kreft new my-app --ts
215
+ ```
216
+
217
+ داخل ملف `.kreft` يمكنك كتابة `interface` و`type` و`enum` و`import type`، و`prop` و`state` و`derive` و`saved` بأنواعها. والتنفيذ لا يحتاج إعدادًا: يستعمل Kreft الأداة `esbuild` إن وُجدت، وإلا إزالة الأنواع المدمجة في Node (22.6+)، وإلا مزيله الخاص بلا اعتماديات.
218
+
219
+ ## تصحيح المشاكل الشائعة
220
+
221
+ | العَرَض | السبب المرجح | الحل |
222
+ |---|---|---|
223
+ | صفحة بيضاء بعد الرفع | `<base href>` خاطئ في `index.html` | ابنِ بـ `--base /` وأعد الرفع |
224
+ | `/docs` يعطي 404 عند التحديث | ملف `.htaccess` لم يُرفع | ارفعه (أظهر الملفات المخفية) |
225
+ | بقاء النسخة القديمة بعد الرفع | تخزين المتصفح أو الاستضافة | تأكد من رفع كل الملفات الجديدة بالبصمات |
226
+ | `no such table: …` | ترحيل جديد لم يُنفَّذ | `kreft migrate` |
227
+ | لا شيء يتغير في الصفحة | سطر `const` في السكربت | استعمل `state` أو `derive` |
228
+ | الإرسال لا يعمل مع `type="email"` | تحقق المتصفح الأصلي يسبق Kreft | أضف `novalidate` إلى `<form>` |
229
+
230
+ ## تمارين
231
+
232
+ 1. ابنِ تطبيقك بـ `--base /` وافتح `dist/index.html` وتحقق من وسم `<base>`.
233
+ 2. أضف `backend/routes/seo.js` لمدونتك وافتح صفحة مقال بمتصفح يحاكي زاحفًا: `curl -A Googlebot …`.
234
+ 3. اكتب اختبار نموذج لـ `Product` يتحقق من أن `scopeInStock` يستثني المنتجات التي مخزونها صفر.
@@ -0,0 +1,258 @@
1
+ # الفصل العاشر: تطبيقات سطح المكتب مع Electron
2
+
3
+ يمكن لـ Kreft أن يحزم تطبيقك كبرنامج سطح مكتب لـ Windows وmacOS وLinux. الصفحات هي ملفات `.kreft` نفسها؛ وElectron يقدّم النافذة فقط.
4
+
5
+ ## البداية السريعة
6
+
7
+ ```bash
8
+ kreft new my-app --electron # تطبيق جديد بدعم سطح المكتب
9
+ # أو في تطبيق موجود:
10
+ kreft electron:init # اسم بديل: kreft make:electron
11
+ npm install # يثبّت electron و electron-builder
12
+ kreft electron # يفتح التطبيق في نافذته: بلا متصفح وبلا عنوان
13
+ kreft electron:build # مثبّت في dist-electron/
14
+ ```
15
+
16
+ للمساعدة في الطرفية في أي وقت:
17
+
18
+ ```bash
19
+ kreft electron:help
20
+ ```
21
+
22
+ ## الأوامر
23
+
24
+ | الأمر | ماذا يفعل |
25
+ |---|---|
26
+ | `kreft electron:init` | يكتب `electron/main.js` و`electron/preload.js` وأيقونة التطبيق `build/icon.png`، ويضيف السكربتات واعتماديات `electron` و`electron-builder` وكتلة `build` إلى `package.json`. الملفات الموجودة لا تُستبدل أبدًا. ويزيل أيضًا روابط Google Fonts من `index.html` ليبدأ التطبيق بلا شبكة. |
27
+ | `kreft electron` | يفتح التطبيق في نافذة سطح مكتب فقط: لا متصفح ولا عنوان يُطبع. خادم التطوير يعمل مخفيًا على منفذ خاص بحاسوبك لا تستعمله إلا النافذة (إعادة التحميل الفورية تعمل). إغلاق النافذة يوقف الخادم. |
28
+ | `kreft electron:build` | يشغّل `kreft build --base ./` ثم `electron-builder`. |
29
+ | `npm run electron:build:mac` | `.dmg` و`.zip`. |
30
+ | `npm run electron:build:win` | مثبّت NSIS و`.exe` محمول. |
31
+ | `npm run electron:build:linux` | AppImage و`.deb` و`.rpm`. |
32
+ | `npm run electron:build:all` | الثلاثة. |
33
+ | `kreft electron:help` | دليل مختصر في الطرفية. |
34
+
35
+ ## مرجع سريع
36
+
37
+ | أريد أن… | افعل هذا |
38
+ |---|---|
39
+ | أضيف دعم سطح المكتب | `kreft new my-app --electron`، أو `kreft electron:init` ثم `npm install` |
40
+ | أفتح التطبيق في نافذته | `kreft electron` |
41
+ | أفتح DevTools | `kreft electron --devtools=bottom` أو `ELECTRON_DEVTOOLS=right` أو F12 |
42
+ | أظهر القائمة أو أخفيها | `ELECTRON_MENU=show` أو `auto` أو `hide`؛ و`kreftDesktop.setMenu('hide')` |
43
+ | أغيّر الأيقونة | استبدل `build/icon.png` (PNG مربعة 512×512 أو أكبر) |
44
+ | أغيّر اسم التطبيق | `build.productName` و`build.appId` في `package.json` |
45
+ | أصنع مثبّتًا | `npm run electron:build:mac` أو `:win` أو `:linux` أو `:all` |
46
+
47
+ ## بنية المشروع
48
+
49
+ ```text
50
+ my-app/
51
+ ├── electron/
52
+ │ ├── main.js النافذة والقائمة وجسر النظام
53
+ │ └── preload.js ما تراه صفحاتك من النظام (window.kreftDesktop)
54
+ ├── build/icon.png أيقونة التطبيق
55
+ ├── dist/ البناء الثابت (kreft build --base ./)
56
+ ├── dist-electron/ المثبّتات التي يكتبها electron-builder
57
+ └── package.json "main": "electron/main.js" وكتلة "build"
58
+ ```
59
+
60
+ ## كيف يعمل
61
+
62
+ - أثناء التطوير: خادم Kreft المخفي يخدّم الصفحات، والنافذة تفتحه. لا متصفح يُفتح ولا عنوان يُطبع.
63
+ - في التطبيق المحزوم: النافذة تحمّل `dist/index.html` مباشرة من الملفات، بلا خادم.
64
+
65
+ ## اكتشاف تطبيق سطح المكتب
66
+
67
+ ```js
68
+ if (Kreftjs.isElectron) {
69
+ const info = await kreftDesktop.getInfo() // { name, version, platform, arch, isPackaged }
70
+ }
71
+ ```
72
+
73
+ ```html
74
+ <!-- components/Titlebar.kreft -->
75
+ state info = null
76
+ on start { if (Kreftjs.isElectron) info = await kreftDesktop.getInfo() }
77
+
78
+ <view>
79
+ <footer k-if="info">{info.name} v{info.version} · {info.platform}</footer>
80
+ </view>
81
+ ```
82
+
83
+ ## جسر سطح المكتب
84
+
85
+ `window.kreftDesktop` (وكذلك `Kreftjs.desktop`) هو الطريقة الوحيدة التي تصل بها صفحاتك إلى النظام. لا شيء آخر من Node.js أو Electron مكشوف.
86
+
87
+ | الدالة | ماذا تفعل |
88
+ |---|---|
89
+ | `getInfo()` | اسم التطبيق والإصدار والنظام. |
90
+ | `minimize()` و`maximize()` و`close()` | التحكم بالنافذة. |
91
+ | `getMenu()` و`setMenu('show' \| 'auto' \| 'hide')` | قائمة النافذة. |
92
+ | `openDevTools(mode)` و`closeDevTools()` و`toggleDevTools()` | أدوات المطوّر. |
93
+ | `showMessageBox(options)` | مربع رسالة أصلي. |
94
+ | `showOpenDialog(options)` و`showSaveDialog(options)` | نوافذ اختيار الملفات. |
95
+
96
+ ```html
97
+ action confirmDelete() {
98
+ const r = await kreftDesktop.showMessageBox({
99
+ type: 'warning',
100
+ buttons: ['حذف', 'إلغاء'],
101
+ defaultId: 1,
102
+ cancelId: 1,
103
+ title: 'تأكيد',
104
+ message: 'هل تريد حذف هذا العنصر؟',
105
+ })
106
+ if (r.response === 0) await remove()
107
+ }
108
+ ```
109
+
110
+ ## إضافة دالة سطح مكتب خاصة بك
111
+
112
+ 1. في `electron/main.js` أضف معالجًا: `ipcMain.handle('app:ping', () => 'pong')`.
113
+ 2. في `electron/preload.js` أضفه إلى كائن `desktop`: `ping: () => ipcRenderer.invoke('app:ping')`.
114
+ 3. استعمله من الصفحة: `await kreftDesktop.ping()`.
115
+
116
+ > **تنبيه أمني:** مرّر الحد الأدنى من البيانات، وتحقق منها في `main.js`. هذا جسر بين صفحة (قد تُحقن فيها شيفرة) ونظام التشغيل.
117
+
118
+ ## أدوات المطوّر
119
+
120
+ ```bash
121
+ kreft electron --devtools # على اليمين
122
+ kreft electron --devtools=bottom # أسفل أو left أو detach
123
+ kreft electron --no-devtools
124
+ ELECTRON_DEVTOOLS=bottom kreft electron
125
+ ```
126
+
127
+ والمفتاح F12 (أو Ctrl+Shift+I) يبدّل اللوحة.
128
+
129
+ ## قائمة النافذة
130
+
131
+ اضبط شريط القائمة عند بدء التطبيق:
132
+
133
+ ```bash
134
+ ELECTRON_MENU=show kreft electron # الافتراضي: الشريط ظاهر
135
+ ELECTRON_MENU=auto kreft electron # مخفي، اضغط Alt لإظهاره (Windows وLinux)
136
+ ELECTRON_MENU=hide kreft electron # بلا قائمة
137
+ ```
138
+
139
+ أو غيّرها والتطبيق يعمل من صفحة:
140
+
141
+ ```js
142
+ window.kreftDesktop.setMenu('hide') // 'show' | 'auto' | 'hide'
143
+ window.kreftDesktop.getMenu() // الوضع الحالي
144
+ ```
145
+
146
+ على macOS تعيش القائمة في الشريط العلوي للشاشة، فـ `show` و`auto` متشابهان، و`hide` يُبقي قائمة اسم التطبيق (فيها Quit) لأن macOS يحتاج واحدة. ولقائمتك الخاصة (File, Edit…) استعمل `Menu.buildFromTemplate([...])` و`Menu.setApplicationMenu(...)` في `electron/main.js`.
147
+
148
+ > **للتطبيقات التي أُنشئت قبل 0.0.18:** ملف `electron/main.js` القديم بلا هذه الميزة. انسخ تعديلاتك احتياطيًا، واحذف الملف، وشغّل `kreft electron:init`.
149
+
150
+ ## أيقونة التطبيق
151
+
152
+ يضع `kreft electron:init` شعار Kreft في `build/icon.png`. استبدله بأيقونتك: PNG مربعة 512×512 أو أكبر. تستعملها النافذة، ويصنع electron-builder منها `.icns` (macOS) و`.ico` (Windows). واسم التطبيق في `build.productName` و`build.appId` داخل `package.json`.
153
+
154
+ يحتاج electron-builder أيضًا إلى `description` و`homepage` و`author` (مع بريد) و`build.linux.maintainer` (لـ `.deb` و`.rpm`). الأمران `kreft electron:init` و`kreft electron:build` يملآن الناقص منها من اسمك وبريدك في git؛ راجعها قبل الإصدار.
155
+
156
+ ## المثبّتات
157
+
158
+ ```bash
159
+ npm run electron:build:mac # .dmg و .zip
160
+ npm run electron:build:win # مثبّت NSIS و .exe محمول
161
+ npm run electron:build:linux # AppImage و .deb و .rpm
162
+ npm run electron:build:all # الثلاثة
163
+ ```
164
+
165
+ تُكتب في `dist-electron/`. والوسائط تذهب إلى electron-builder، مثل `kreft electron:build --mac --arm64`. الإعدادات الافتراضية في كتلة `build` من `package.json`:
166
+
167
+ | النظام | الأهداف |
168
+ |---|---|
169
+ | Windows | مثبّت `nsis` (تختار المجلد) و`portable` |
170
+ | macOS | `dmg` و`zip` |
171
+ | Linux | `AppImage` و`deb` و`rpm` |
172
+
173
+ - ابنِ كل نظام على نظامه. على Mac تُبنى AppImage ومثبّتات Windows، لكن `.deb` و`.rpm` تفشل: ابنهما على Linux، أو احذفهما من `build.linux.target`.
174
+ - توقيع الشيفرة (code signing) يُضبط عبر electron-builder (electron.build/code-signing) ولازم قبل تسليم التطبيق للناس؛ تطبيقات macOS غير الموقّعة تعرض تحذير Gatekeeper.
175
+ - **التطبيق المحزوم لا يشغّل واجهة خلفية.** يحمّل `dist/index.html` فقط. تطبيق الواجهة وحدها يعمل كما هو؛ أما التطبيق المتكامل (تسجيل دخول وقاعدة بيانات) فلا يعمل بعد التثبيت ما لم تشغّل خادمًا في مكان ما وتوجّه `api.setup({ base })` إليه.
176
+
177
+ ## `npm run build` أم `electron:build`؟
178
+
179
+ إضافة Electron لا تغيّر `npm run build`. الأمران يصنعان شيئين مختلفين:
180
+
181
+ | الأمر | ماذا يصنع | استعمله لـ |
182
+ |---|---|---|
183
+ | `npm run build` | الموقع في `dist/`، بمسارات تبدأ بـ `/` (ومجلد `docs/` مضمَّن). | نشر التطبيق على خادم ويب. |
184
+ | `npm run electron:build` | الموقع نفسه مبنيًا بـ `--base ./` ليُفتح من ملف، ثم مثبّت في `dist-electron/`. | تسليم التطبيق كبرنامج سطح مكتب. |
185
+
186
+ `dist/` الناتج عن `npm run build` يعرض نافذة بيضاء إن فتحته في Electron لأن مساراته تبدأ بـ `/`. شغّل `electron:build` (أو `kreft build --base ./`) أولًا. ولا مانع من الاثنين: `electron:build` يعيد كتابة `dist/`، فشغّل `npm run build` من جديد قبل نشر الموقع.
187
+
188
+ ## الأمان
189
+
190
+ النافذة تتبع إرشادات Electron الأمنية:
191
+
192
+ - `contextIsolation: true` و`nodeIntegration: false` و`sandbox: true`: صفحتك لا ترى Node.js.
193
+ - الروابط الخارجية تُفتح في المتصفح الافتراضي للنظام، لا داخل النافذة.
194
+ - التنقل بعيدًا عن أصل التطبيق ممنوع.
195
+ - الجسر يمرر حقولًا مسموحة فقط إلى نوافذ الحوار.
196
+
197
+ ## استكشاف الأخطاء
198
+
199
+ | الرسالة أو العَرَض | الحل |
200
+ |---|---|
201
+ | `Electron is not installed locally` | `kreft add -D electron` |
202
+ | `electron-builder is not installed` | `kreft add -D electron-builder` |
203
+ | نافذة بيضاء في التطبيق المحزوم | أعد تشغيل `electron:build` (يلزمه `--base ./`) وتأكد من وجود `dist/index.html` |
204
+ | `.deb` أو `.rpm` تفشل على Mac | ابنهما على Linux أو احذفهما من `build.linux.target` |
205
+ | خطأ author/maintainer/homepage عند بناء Linux | أضف `author` ببريد و`homepage` و`build.linux.maintainer` في `package.json` |
206
+ | لا أستطيع إخفاء القائمة | استعمل `ELECTRON_MENU=hide`؛ وللتطبيقات القديمة أعد توليد `electron/main.js` |
207
+
208
+ ## مثال: تطبيق ملاحظات لسطح المكتب (واجهة فقط)
209
+
210
+ تطبيق لا يحتاج خادمًا: الملاحظات تُحفظ بـ `saved` في الجهاز، وأوامر النظام عبر الجسر.
211
+
212
+ ```html
213
+ <!-- pages/Notes.kreft -->
214
+ saved notes = [] // تبقى بعد إغلاق التطبيق
215
+ state text = ''
216
+ state info = null
217
+
218
+ on start { if (Kreftjs.isElectron) info = await kreftDesktop.getInfo() }
219
+
220
+ action add() {
221
+ if (!text.trim()) return
222
+ notes.unshift({ id: Date.now(), text: text.trim() })
223
+ text = ''
224
+ }
225
+
226
+ action removeNote(n) {
227
+ if (Kreftjs.isElectron) {
228
+ const r = await kreftDesktop.showMessageBox({
229
+ type: 'question', buttons: ['حذف', 'إلغاء'], defaultId: 1, cancelId: 1,
230
+ message: 'حذف هذه الملاحظة؟',
231
+ })
232
+ if (r.response !== 0) return
233
+ }
234
+ notes = notes.filter((x) => x.id !== n.id)
235
+ }
236
+
237
+ action hideMenu() { kreftDesktop.setMenu('hide') }
238
+
239
+ <view>
240
+ <h1>ملاحظاتي</h1>
241
+ <form novalidate @submit.prevent={add}>
242
+ <input k-model="text" placeholder="اكتب ملاحظة…">
243
+ </form>
244
+
245
+ <ul>
246
+ <li k-each="n in notes" k-key="n.id">{n.text} <button @click="removeNote(n)">✕</button></li>
247
+ </ul>
248
+
249
+ <p k-if="info">{info.name} {info.version} · {info.platform}</p>
250
+ <button k-if="Kreftjs.isElectron" @click="hideMenu">أخفِ القائمة</button>
251
+ </view>
252
+ ```
253
+
254
+ ## تمارين
255
+
256
+ 1. أنشئ تطبيق سطح مكتب بـ `kreft new notes --electron`، وغيّر الأيقونة، وابنِ `.dmg` أو `.exe`.
257
+ 2. أضف دالة `ping` خاصة بك عبر `ipcMain` و`preload.js`.
258
+ 3. ابنِ للنظامين وقارن حجم المثبّتين.