kreftjs 0.0.19-beta → 0.0.21-beta

package/README.md

@@ -24,7 +24,7 @@ action add() { count++ }
 You need [Node.js](https://nodejs.org) 22.5 or newer.
 
 ```bash
-npm i -g kreftjs          # once: makes the `kreft` command available everywhere
+npm install -g kreftjs@latest   # once: makes the `kreft` command available everywhere
 kreft new my-app        # asks: JavaScript or TypeScript?
 cd my-app
 npm run dev
@@ -42,6 +42,15 @@ Open the address in the terminal (normally `http://localhost:8000`). A new proje
 | **Authentication** | Cookie sessions with CSRF protection, API tokens with permissions, device list, two-factor codes, email verification, account lockout. |
 | **Tooling** | `kreft dev` with hot reload, DevTools, an error monitor, `kreft build` (CSP-safe), prerendering, TypeScript, Vite and Electron support, a safer `kreft add`, an MCP server for AI agents. |
 
+## Put it online
+
+```bash
+npm install kreftjs@latest       # the newest version
+npm run build                    # the finished site, ready to upload
+```
+
+Upload what is inside the output folder (`dist/`; for this repository's own website, `dist/kreftjs-com`) to your host. The kreftjs.com steps, and releasing a new package version with `npm publish`, are in [Publish the website](docs/README.md#publish-the-website-kreftjscom).
+
 ## Desktop apps (Electron)
 
 ```bash
@@ -65,6 +74,7 @@ The app icon is `build/icon.png`, and `ELECTRON_MENU=show|auto|hide` controls th
 
 | I want to… | Read |
 |---|---|
+| Learn Kreft in Arabic, from basics to advanced tested examples | [كتاب Kreft بالعربية](book/ar/README.md) |
 | Build my first page | [Your first app](docs/README.md#your-first-app) and [Components](docs/README.md#components-and-the-kreft-file) |
 | Fetch data and handle forms | [Fetching data](docs/README.md#fetching-data), [Forms](docs/README.md#forms-and-validation) |
 | Add an API and a database | [Routing](docs/README.md#routing), [Models](docs/README.md#models-and-the-database), [Migrations](docs/README.md#migrations-seeders-and-factories) |

package/bin/backend/http.js

@@ -96,6 +96,8 @@ const cookieSecure = () => {
 function response(body, status = 200, headers = {}) { return new Response(body, status, headers); }
 response.json = (body, status = 200, headers = {}) => new Response(body, status, headers);
 response.noContent = () => new Response(undefined, 204);
+// response.stream('/path/video.mp4') - sends a file with byte-range support (seeking, Safari); { type, download, headers }
+response.stream = (file, opts = {}) => { const r = new Response(undefined, 200); r.streamFile = { file, ...opts }; return r; };
 const noContent = () => new Response(undefined, 204);
 const toResponse = (v) => (v instanceof Response ? v : v === undefined ? new Response(undefined, 204) : new Response(v, 200));
 
@@ -313,8 +315,10 @@ class Request {
         if (kind === 'unique' && ignore && ignore !== 'NULL') { sql += ` AND ${conn.q(idColumn)} != ?`; params.push(ignore); }
         const found = (await conn.query(sql + ' LIMIT 1', params)).length > 0;
         const label = (names && names[field]) || field.replace(/_/g, ' ');
-        if (kind === 'unique' && found) (errors[field] = errors[field] || []).push(`The ${label} has already been taken.`);
-        if (kind === 'exists' && !found) (errors[field] = errors[field] || []).push(`The selected ${label} is invalid.`);
+        // your own message for the rule: { 'title.unique': 'That title is already used.' }
+        const own = messages && (messages[`${field}.${kind}`] || messages[kind]);
+        if (kind === 'unique' && found) (errors[field] = errors[field] || []).push(own || `The ${label} has already been taken.`);
+        if (kind === 'exists' && !found) (errors[field] = errors[field] || []).push(own || `The selected ${label} is invalid.`);
       }
     }
     if (Object.keys(errors).length) throw new ValidationError(errors);

package/bin/backend/index.js

@@ -273,6 +273,10 @@ const SECURITY_HEADERS = {
   });
   const send = (res, r) => {
     if (res.headersSent || res.writableEnded) return;
+    if (r.streamFile) { // response.stream(file): byte ranges for video and audio
+      const { file, ...o } = r.streamFile;
+      return require('./stream.js').sendFile(res.req, res, file, { ...o, headers: { 'Cache-Control': 'no-store', ...SECURITY_HEADERS, ...r.headers, ...(o.headers || {}) } });
+    }
     const status = r.statusCode || 200;
     const noBody = status === 204 || status === 304 || r.body === undefined;
     const isHtml = typeof r.body === 'string' && (r.headers && r.headers['Content-Type'] && r.headers['Content-Type'].includes('text/html'));

package/bin/backend/stream.js

@@ -0,0 +1,74 @@
+// Sending a file the way a video player needs it: byte ranges (206), so the browser can seek and Safari plays at all.
+const fs = require('fs');
+const path = require('path');
+
+const MEDIA_TYPES = {
+  '.mp4': 'video/mp4', '.m4v': 'video/mp4', '.webm': 'video/webm', '.ogv': 'video/ogg', '.mov': 'video/quicktime', '.mkv': 'video/x-matroska',
+  '.mp3': 'audio/mpeg', '.m4a': 'audio/mp4', '.aac': 'audio/aac', '.ogg': 'audio/ogg', '.oga': 'audio/ogg', '.wav': 'audio/wav', '.opus': 'audio/ogg', '.flac': 'audio/flac',
+  '.m3u8': 'application/vnd.apple.mpegurl', '.ts': 'video/mp2t', '.m4s': 'video/iso.segment', '.mpd': 'application/dash+xml', '.vtt': 'text/vtt',
+};
+
+// "bytes=0-99", "bytes=100-", "bytes=-500" -> { start, end } | null (no range) | false (cannot be satisfied)
+function parseRange(header, size) {
+  if (!header) return null;
+  const m = /^bytes=(\d*)-(\d*)$/.exec(String(header).trim()); // one range only; several ranges are answered with the whole file
+  if (!m || (m[1] === '' && m[2] === '')) return null;
+  let start, end;
+  if (m[1] === '') { // the last N bytes
+    const n = Number(m[2]);
+    if (n === 0) return false;
+    start = Math.max(0, size - n); end = size - 1;
+  } else {
+    start = Number(m[1]);
+    end = m[2] === '' ? size - 1 : Math.min(Number(m[2]), size - 1);
+  }
+  if (!Number.isFinite(start) || !Number.isFinite(end) || start > end || start >= size) return false;
+  return { start, end };
+}
+
+// sendFile(req, res, file, { type, headers, status, download })
+function sendFile(req, res, file, opts = {}) {
+  req = req || res.req;
+  let stat;
+  try { stat = fs.statSync(file); if (!stat.isFile()) throw new Error('not a file'); } catch (_) {
+    if (!res.headersSent) res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+    return res.end('Not found');
+  }
+  const size = stat.size;
+  const type = opts.type || MEDIA_TYPES[path.extname(file).toLowerCase()] || 'application/octet-stream';
+  const etag = `W/"${size.toString(16)}-${Math.floor(stat.mtimeMs).toString(16)}"`;
+  const headers = {
+    'Content-Type': type,
+    'Accept-Ranges': 'bytes',
+    'Last-Modified': stat.mtime.toUTCString(),
+    ETag: etag,
+    'X-Content-Type-Options': 'nosniff',
+    ...(opts.download ? { 'Content-Disposition': `attachment; filename*=UTF-8''${encodeURIComponent(path.basename(file))}` } : {}),
+    ...(opts.headers || {}),
+  };
+  const method = (req && req.method) || 'GET';
+  const h = (req && req.headers) || {};
+
+  if (h['if-none-match'] === etag && !h.range) { res.writeHead(304, headers); return res.end(); }
+
+  let range = parseRange(h.range, size);
+  // If-Range: only honor the range when the file is still the one the client started with
+  if (range && h['if-range'] && h['if-range'] !== etag && h['if-range'] !== headers['Last-Modified']) range = null;
+  if (range === false) {
+    res.writeHead(416, { 'Content-Range': `bytes */${size}`, 'Content-Type': 'text/plain; charset=utf-8' });
+    return res.end('Range not satisfiable');
+  }
+
+  let status = opts.status || 200, start = 0, end = size - 1;
+  if (range) { status = 206; ({ start, end } = range); headers['Content-Range'] = `bytes ${start}-${end}/${size}`; }
+  headers['Content-Length'] = size === 0 ? 0 : end - start + 1;
+  res.writeHead(status, headers);
+  if (method === 'HEAD' || size === 0) return res.end();
+
+  const stream = fs.createReadStream(file, { start, end });
+  stream.on('error', () => res.destroy());
+  res.on('close', () => stream.destroy()); // the viewer seeked or left: stop reading
+  stream.pipe(res);
+}
+
+module.exports = { sendFile, parseRange, MEDIA_TYPES };

package/bin/build.js

@@ -25,7 +25,7 @@ const path = require('path');
 const Kreftjs = require('../kreftjs.js');
 
 const { expandBlocks, prepareTemplate, splitKreft, splitInterp, exactBrace, stripBrace, interpToExpr, quoteBraceAttrs, expandSelfClosing,
-  scopeCss, hashString, propType, simplePathRE, fnExpRE, forAliasRE, stripTypeScript } = Kreftjs.__internal;
+  scopeCss, hashString, propType, typeCheck, caseCond, simplePathRE, fnExpRE, forAliasRE, stripTypeScript } = Kreftjs.__internal;
 
 const deps = require('./deps.js');
 // component files: .kreft, or .kreftjs in a project from the 0.0.x betas
@@ -34,12 +34,13 @@ const SERVER_DIRS = new Set();
 const SKIP = new Set(['node_modules', 'dist', 'dist-electron', '.git', '.vscode', '.idea', 'package.json', 'package-lock.json', '.DS_Store']);
 
 module.exports = function build(args) {
-  let folder = null, out = null, base = null, prerender = null, urlsFile = null, htaccess = true;
+  let folder = null, out = null, base = null, prerender = null, urlsFile = null, htaccess = true, minify = true;
   const include = [];
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--out' || args[i] === '-o') out = args[++i];
     else if (args[i] === '--base') base = args[++i];
     else if (args[i] === '--no-htaccess') htaccess = false;
+    else if (args[i] === '--no-minify') minify = false; // keep kreftjs.js readable (for debugging)
     else if (args[i] === '--include') include.push(args[++i]); // another folder to copy in, like the docs
     else if (args[i] === '--prerender') prerender = args[i + 1] && !args[i + 1].startsWith('-') && args[i + 1].includes('/') ? args[++i].split(',') : [];
     else if (args[i] === '--urls') urlsFile = args[++i]; // a file with more addresses to prerender (pages from your data)
@@ -154,7 +155,17 @@ ${indent(components.join('\n\n'))}
       }
     }
   }
-  fs.copyFileSync(path.join(__dirname, '..', 'kreftjs.js'), path.join(dist, 'kreftjs.js'));
+  // the framework file is minified when esbuild is installed (about 40% smaller); without it, it is copied as it is
+  const runtimeSrc = path.join(__dirname, '..', 'kreftjs.js'), runtimeOut = path.join(dist, 'kreftjs.js');
+  const esb = minify ? deps.loadEsbuild(root) : null;
+  let minified = false;
+  if (esb) {
+    try {
+      fs.writeFileSync(runtimeOut, esb.transformSync(fs.readFileSync(runtimeSrc, 'utf8'), { minify: true, target: 'es2020', legalComments: 'none' }).code);
+      minified = true;
+    } catch (_) { /* fall back to the plain copy */ }
+  }
+  if (!minified) fs.copyFileSync(runtimeSrc, runtimeOut);
   for (const dir of include) {
     const from = path.resolve(dir);
     if (!fs.existsSync(from)) fail(`--include: ${dir} does not exist.`);
@@ -318,12 +329,16 @@ function compileFile(file, rel, root) {
 
   // props: keep the default as a function so every instance gets its own copy
   const props = Object.entries(sp.props).map(([p, expr]) => {
-    if (expr == null) return `${JSON.stringify(p)}: {}`;
+    // `prop size: 'sm' | 'lg'`: the type text is kept, so the built app warns about a wrong value too
+    const ti = sp.propTypes && sp.propTypes[p];
+    const simple = ti && { string: 'String', number: 'Number', boolean: 'Boolean' }[ti.type.trim()];
+    const typed = ti ? `, typeText: ${JSON.stringify(ti.type)}, check: Kreftjs.__typeCheck(${JSON.stringify(ti.type)})${ti.required ? ', required: true' : ''}` : '';
+    if (expr == null) return `${JSON.stringify(p)}: { ${simple ? `type: ${simple}` : ''}${typed} }`.replace('{ , ', '{ ').replace('{  }', '{}');
     let sample;
     try { sample = new Function(`return (${expr})`)(); } catch (_) { /* uses something only known at runtime */ }
-    if (typeof sample === 'function') return `${JSON.stringify(p)}: { type: Function, default: (${expr}) }`;
+    if (typeof sample === 'function') return `${JSON.stringify(p)}: { type: Function, default: (${expr})${typed} }`;
     const type = propType(sample);
-    return `${JSON.stringify(p)}: { ${type ? `type: ${type.name}, ` : ''}default: function () { return (${expr}); } }`;
+    return `${JSON.stringify(p)}: { ${type ? `type: ${type.name}, ` : ''}default: function () { return (${expr}); }${typed} }`;
   });
 
   // imports: other .kreft files become component references; .js modules load with import()
@@ -428,12 +443,15 @@ function addRouterTemplates(fns) {
   addHandler(fns, 'navigate($event)');
 }
 
-const STRUCTURAL = new Set(['if', 'elif', 'else', 'each', 'key', 'ref', 'skip', 'cloak', 'slot', 'empty', 'once', 'animate', 'waiting', 'failed']);
+const STRUCTURAL = new Set(['match', 'case', 'default', 'if', 'elif', 'else', 'each', 'key', 'ref', 'skip', 'cloak', 'slot', 'empty', 'once', 'animate', 'waiting', 'failed']);
 
 function collectExpressions(template, fns) {
   const html = prepareTemplate(template);
+  const subjects = []; // k-match subjects seen so far: a k-case is compared with one of them
   scanHtml(html, {
     attr(name, value) {
+      if (name === 'k-match') { const v = stripBrace(value); subjects.push(v); return addEval(fns, v); }
+      if (name === 'k-case') { const raw = stripBrace(value); for (const sub of subjects) addEval(fns, caseCond(sub, raw)); return; }
       if (name[0] === ':' || name === 'k-bind' || name.startsWith('k-bind:')) return addEval(fns, value);
       if (name[0] === '@' || name.startsWith('k-on:')) return addHandler(fns, stripBrace(value));
       if (name.startsWith('k-')) {

package/bin/kreftjs.js

@@ -165,6 +165,7 @@ function help() {
         --prerender [paths] Also save every page as ready HTML (needs: npm i -D jsdom)
         --include <folder>  Also copy this folder into the output (for example docs)
         --no-htaccess       Do not write dist/.htaccess (page-address rules for Apache and Hostinger)
+        --no-minify         Copy kreftjs.js as it is (by default it is minified when esbuild is installed)
     kreft add <packages...>     Install npm packages with strict security gatekeeper (alias: kreft install, kreft i)
         -D, --dev           Install as devDependency
         -y, --yes           Auto-confirm unverified community packages in CI/CD
@@ -582,6 +583,30 @@ function copyFolder(from, to) {
 }
 
 /* ------------------------------------------------------------------ kreft vscode */
+/* VS Code only loads extensions listed in extensions.json, and after "Uninstall" it keeps the folder in .obsolete and
+   deletes it on the next start. Copying the folder is not enough after an uninstall: list it again and clear .obsolete. */
+function registerExtension(dir, folder, version) {
+  const id = 'kreft.kreftjs';
+  const location = path.join(dir, folder);
+  try {
+    const file = path.join(dir, 'extensions.json');
+    let list = [];
+    if (fs.existsSync(file)) { try { list = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { list = []; } }
+    if (!Array.isArray(list)) list = [];
+    list = list.filter((e) => !(e && e.identifier && /^kreft\.kreft(js)?$/.test(e.identifier.id)));
+    list.push({ identifier: { id }, version, location: { $mid: 1, fsPath: location, external: 'file://' + location, path: location, scheme: 'file' }, relativeLocation: folder, metadata: { installedTimestamp: Date.now(), pinned: false, source: 'resource', isApplicationScoped: false, isMachineScoped: false, isBuiltin: false, targetPlatform: 'undefined' } });
+    fs.writeFileSync(file, JSON.stringify(list));
+  } catch {}
+  try {
+    const file = path.join(dir, '.obsolete');
+    if (fs.existsSync(file)) {
+      const o = JSON.parse(fs.readFileSync(file, 'utf8'));
+      for (const k of Object.keys(o)) if (k.startsWith('kreft.kreftjs-') || k.startsWith('kreft.kreft-')) delete o[k];
+      fs.writeFileSync(file, JSON.stringify(o));
+    }
+  } catch {}
+}
+
 function installVscode() {
   const os = require('os');
   const from = path.join(__dirname, '..', 'editors', 'vscode');
@@ -594,6 +619,7 @@ function installVscode() {
     fs.mkdirSync(dir, { recursive: true });
     fs.readdirSync(dir).filter((n) => n.startsWith('kreft.kreftjs-') || n.startsWith('kreft.kreft-')) /* the older extensions go too */.forEach((n) => fs.rmSync(path.join(dir, n), { recursive: true, force: true }));
     copyFolder(from, path.join(dir, `kreft.kreftjs-${ext.version}`));
+    registerExtension(dir, `kreft.kreftjs-${ext.version}`, ext.version);
     console.log(`  Installed in ${path.join(dir, `kreft.kreftjs-${ext.version}`)}`);
   }
   // Ensure current project .vscode/settings.json maps .kreft files to Kreft and configures formatter
@@ -735,7 +761,7 @@ async function devServer(args, { production = false } = {}) {
     '.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript', '.kreft': 'text/plain', '.kreftjs': 'text/plain',
     '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png',
     '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp',
-    '.ico': 'image/x-icon', '.woff2': 'font/woff2', '.woff': 'font/woff', '.txt': 'text/plain', '.md': 'text/markdown',
+    '.ico': 'image/x-icon', ...(({ '.ts': _ts, ...media }) => media)(require('./backend/stream.js').MEDIA_TYPES), '.woff2': 'font/woff2', '.woff': 'font/woff', '.txt': 'text/plain', '.md': 'text/markdown',
   };
   const isFile = (p) => { try { return fs.statSync(p).isFile(); } catch (_) { return false; } };
 
@@ -753,12 +779,15 @@ async function devServer(args, { production = false } = {}) {
       }
     }
     const type = types[path.extname(file).toLowerCase()] || 'application/octet-stream';
-    res.writeHead(opts.status || 200, {
+    const fileHeaders = {
       'Content-Type': type + (type.startsWith('text/') || type.endsWith('json') ? '; charset=utf-8' : ''),
       'Cache-Control': isProd ? 'no-cache' : 'no-store', // dev: always pick up your latest changes
       'X-Content-Type-Options': 'nosniff',
       ...prodHeaders,
-    });
+    };
+    // everything but pages is sent with byte ranges (video and audio seek, Safari plays)
+    if (type !== 'text/html') return require('./backend/stream.js').sendFile(res.req, res, file, { status: opts.status, type: fileHeaders['Content-Type'], headers: fileHeaders });
+    res.writeHead(opts.status || 200, fileHeaders);
     if (!production && type === 'text/html') {
       let html = fs.readFileSync(file, 'utf8');
       // PUBLIC_ values from .env, as Kreftjs.env (kreft build puts them in app.js)
@@ -793,12 +822,9 @@ async function devServer(args, { production = false } = {}) {
       return res.end(opts.seo ? require('./backend/seo-pages.js').inject(html, opts.seo) : html);
     }
     if (type === 'text/html' && opts.seo) return res.end(require('./backend/seo-pages.js').inject(fs.readFileSync(file, 'utf8'), opts.seo));
-    const stream = fs.createReadStream(file);
-    stream.on('error', () => {
-      if (!res.headersSent) res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
-      res.end('Not found');
-    });
-    stream.pipe(res);
+    const page = fs.createReadStream(file); // a page in production: headers are written, send it whole
+    page.on('error', () => res.end('Not found'));
+    page.pipe(res);
   }
 
   // ----- hot reload: watch the folder, tell open pages what changed -----
@@ -1108,8 +1134,7 @@ async function devServer(args, { production = false } = {}) {
         const realPub = real(pub), realF = real(f);
         if ((f.startsWith(pub + path.sep)) && !secret(urlPath) && isFile(f) && realPub && realF && realF.startsWith(realPub + path.sep)) {
           const type = types[path.extname(f).toLowerCase()] || 'application/octet-stream';
-          res.writeHead(200, { 'Content-Type': type, 'X-Content-Type-Options': 'nosniff', 'Content-Security-Policy': "default-src 'none'; img-src 'self'; style-src 'unsafe-inline'; sandbox", 'Cache-Control': 'public, max-age=3600' });
-          return fs.createReadStream(f).pipe(res);
+          return require('./backend/stream.js').sendFile(req, res, f, { type, headers: { 'Content-Security-Policy': "default-src 'none'; img-src 'self'; media-src 'self'; style-src 'unsafe-inline'; sandbox", 'Cache-Control': /\.(m3u8|mpd)$/i.test(f) ? 'no-cache' : 'public, max-age=3600' } }); // a live playlist changes every few seconds
         }
         res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
         return res.end('Not found: ' + urlPath);

package/book/ar/01-getting-started.md

@@ -0,0 +1,169 @@
+# الفصل الأول: البداية
+
+## ما هو Kreft؟
+
+Kreft (يُكتب `kreftjs`) إطار عمل صغير، تفاعلي (reactive)، له لغة مكوّنات خاصة به: ملفات `.kreft`. تكتب في الملف الواحد حالتك وقيمك المشتقة وأفعالك بكلمات بسيطة، ثم تصف الصفحة في `<view>`. ويأتي مع واجهة خلفية كاملة على Node.js (مسارات، ومتحكمات، ونماذج، وترحيلات، وطوابير، وبريد)، فيغطي المشروع الواحد التطبيق بأكمله.
+
+> **ملاحظة:** الإصدار الحالي تجريبي (`0.0.x-beta`). كل ما في هذا الكتاب جُرِّب على الإصدار الذي صدر معه، لكن واجهات الإطار قد تتغير بين الإصدارات التجريبية. راجع `kreft --version` وملف `docs/README.md` (بالإنجليزية) عند الشك.
+
+لماذا قد تختاره؟
+
+- **لغة واحدة للمكوّن:** HTML ومنطق وتنسيق في ملف واحد، بلا ديكورات ولا وحدات (modules) تتعلمها.
+- **بدون إعداد:** `kreft new` ثم `kreft dev`. لا ملف إعداد لأداة تجميع.
+- **واجهة خلفية جاهزة:** تسجيل دخول، وتحقق من البريد، واستعادة كلمة المرور، ولوحة إدارة، ومصادقة ثنائية.
+- **تطبيقات سطح المكتب:** `kreft new --electron` ثم تبني مثبّتات لـ Windows وmacOS وLinux.
+- **دعم RTL من الأساس:** تبديل اللغة واتجاه الصفحة من دالة واحدة (مهم لنا نحن العرب، وله فصل كامل).
+
+## التثبيت
+
+المتطلبات: Node.js (يُفضَّل 22 أو أحدث) وnpm.
+
+```bash
+npm install -g kreftjs
+kreft --version        # مثال: 0.0.19-beta
+```
+
+للتحقق من أن كل شيء سليم:
+
+```bash
+kreft about
+```
+
+وللحصول على تلوين الملفات وملفات المقتطفات (snippets) في VS Code أو Cursor:
+
+```bash
+kreft vscode
+```
+
+## أول تطبيق
+
+```bash
+kreft new my-app            # يسألك: JavaScript أم TypeScript؟
+cd my-app
+npm run dev
+```
+
+افتح العنوان الذي يطبعه الطرفية (عادة `http://localhost:8000`؛ وإن كان المنفذ مشغولًا يُستخدم التالي).
+
+خيارات مفيدة عند الإنشاء:
+
+```bash
+kreft new shop --db mysql --ts          # TypeScript وقاعدة MySQL
+kreft new site --ui tailwind --no-auth  # Tailwind بدون صفحات تسجيل الدخول
+kreft new desk --electron               # مع دعم تطبيقات سطح المكتب
+kreft new app-name --ui bootstrap --no-auth
+```
+
+> **تنبيه:** اكتب قيم الخيارات كما هي بالضبط: `bootstrap` و`tailwind` و`bulma` و`pico`. أي قيمة أخرى توقف الأمر مع رسالة تعرض القيم المسموحة.
+
+يأتي المشروع الجديد (إن لم تستعمل `--no-auth`) بصفحات الدخول والتسجيل واستعادة كلمة المرور وتأكيد البريد والملف الشخصي ولوحة الإدارة. وعند تشغيل `npm run dev` تُنشأ الجداول ومستخدم تجريبي:
+
+- البريد: `test@example.com`
+- كلمة المرور: `password`
+
+> **تحذير:** هذا المستخدم للتطوير المحلي فقط. احذفه أو لا تشغّل `--seed` أبدًا على قاعدة بيانات حقيقية.
+
+رسائل البريد (تأكيد، استعادة) تُطبع في الطرفية إلى أن تضبط `MAIL_URL`.
+
+## أصغر تطبيق ممكن
+
+يمكنك استعمال Kreft بلا مشروع كامل. التطبيق صفحة HTML وملفات `.kreft`:
+
+```html
+<!-- index.html -->
+<div id="app"></div>
+<script src="kreftjs.js"></script>
+<script>
+  Kreftjs.app('App.kreft').mount('#app')
+</script>
+```
+
+```html
+<!-- App.kreft -->
+state name = 'العالم'
+
+<view>
+  <h1>مرحبًا يا {name}</h1>
+  <input k-model="name">
+</view>
+```
+
+> **تحذير:** ملفات `.kreft` تحتاج خادمًا. المتصفحات ترفض تحميل الملفات من `file://`، فافتح التطبيق دائمًا عبر `npm run dev` أو أي خادم.
+
+## بنية المشروع
+
+ينشئ `kreft new` مجلدين لا يختلطان أبدًا: `frontend/` هو ما يصل المتصفح، و`backend/` هو الخادم ولا يمكن الوصول إليه عبر HTTP.
+
+```text
+my-app/
+├── frontend/
+│   ├── index.html          نقطة الدخول
+│   ├── App.kreft           المكوّن الجذر وحاوية الموجِّه
+│   ├── routes/web.kreft    مسارات الصفحات
+│   ├── layouts/            app.kreft (بعد الدخول)، guest.kreft (صفحات الدخول)
+│   ├── pages/              ملف .kreft لكل شاشة
+│   ├── components/         مكوّنات قابلة لإعادة الاستخدام
+│   ├── ui.css              نظام التصميم
+│   └── tests/              اختبارات المكوّنات
+├── backend/
+│   ├── config/             app.js, auth.js, database.js, redis.js, session.js
+│   ├── app/
+│   │   ├── Http/           Controllers, Middleware, Requests, Resources
+│   │   ├── Models/         User, PersonalAccessToken
+│   │   └── Auth/           مساعدات الجلسات
+│   ├── database/           migrations, seeders, factories
+│   └── routes/             api.js, auth.js, console.js
+├── .env                    الأسرار والإعدادات (لا ترفعه إلى Git أبدًا)
+├── package.json
+└── kreftjs.config.json     خيارات سطر الأوامر
+```
+
+لماذا الفصل مهم؟
+
+- `kreft dev` و`kreft build` يقدّمان `frontend/` فقط. أما `backend/` وملفات قاعدة البيانات و`.env` فلا عنوان ويب لها.
+- على macOS وLinux يمنح `kreft new` المجلد `backend/` والملف `.env` صلاحيات يقرؤها المالك فقط.
+- ملفات مثل `.env` و`*.db` و`*.pem` و`package.json` مرفوضة حتى لو طُلبت بالاسم.
+
+## إضافة مكتبة CSS
+
+أي مكتبة تعمل. أضف `<link>` في `index.html`، أو ثبّتها واستورد ملفها من ملف `.kreft`:
+
+```html
+import 'bootstrap/dist/css/bootstrap.min.css'   // npm i bootstrap
+import './theme.css'                            // ملفك الخاص بجانب هذا الملف
+```
+
+## حزم npm في المتصفح
+
+```bash
+kreft add dayjs nanoid lodash
+kreft add -D esbuild      # مرة واحدة لكل مشروع: يجهّز الحزم للمتصفح
+```
+
+```html
+import dayjs from 'dayjs'
+import { nanoid } from 'nanoid'
+
+state id = nanoid()
+
+<view>
+  <p>{dayjs().format('YYYY-MM-DD')}</p>
+</view>
+```
+
+الأمر `kreft add` نسخة أكثر أمانًا من `npm install`: يمنع سكربتات التثبيت افتراضيًا، ويتحقق من أخطاء الكتابة المتعمدة في أسماء الحزم (typosquatting)، وينبّه إلى الحزم التي نُشرت قبل أقل من 14 يومًا، ثم يشغّل `npm audit`.
+
+## أوامر ستستخدمها كل يوم
+
+| الأمر | وظيفته |
+|---|---|
+| `kreft new my-app` | ينشئ مشروعًا |
+| `kreft dev` | خادم التطوير مع إعادة تحميل فورية |
+| `kreft build` | يصرّف التطبيق إلى ملفات عادية في `dist/` |
+| `kreft serve dist` | يشغّل التطبيق المبني للمستخدمين الحقيقيين |
+| `kreft list` | يعرض كل أوامر نسختك |
+| `kreft help` | خيارات الأوامر الرئيسية |
+| `kreft tinker` | طرفية تفاعلية مع نماذجك (`await User.count()`) |
+| `kreft update` | يحدّث الحزم وملف `kreftjs.js` |
+
+تدريب سريع: أنشئ مشروعًا، وغيّر كلمة في `frontend/pages/` وراقب الصفحة تتبدل في المتصفح دون إعادة تحميل وبدون ضياع الحالة. هذه هي إعادة التحميل الفورية (hot reload).