kreftjs 0.0.20-beta → 0.0.22-beta

package/book/ar/20-pipes-match-props.md

@@ -0,0 +1,75 @@
+# الفصل العشرون: الأنابيب و`k-match` وأنواع الخصائص
+
+ثلاث إضافات تجعل القوالب أقصر وأوضح. كلها تعمل مع `kreft dev` ومع `kreft build` ومع سياسة CSP الصارمة، والصيغة القديمة لا تتأثر.
+
+## 1) الأنابيب (Pipes)
+
+بدل استدعاء دوال مساعدة داخل القالب، مرّر القيمة عبر أنبوب بعلامة `|`:
+
+```html
+<p>{ price | currency:'EUR' }</p>
+<p>{ createdAt | ago }</p>
+<p>{ title | capitalize | truncate:30 }</p>
+<a title={name | upper}>{ tags | join:' · ' }</a>
+```
+
+- الوسائط بعد نقطتين: `truncate:30` و`currency:'EUR'`، أو بين قوسين: `number(2)`.
+- تُسلسل الأنابيب من اليسار إلى اليمين.
+- `||` و`|=` ليستا أنبوبًا، وكذلك `|` داخل نص أو تعبير نمطي أو قوسين.
+- الأرقام والتواريخ تتبع لغة التطبيق الحالية (`Kreftjs.locale`)، فيتغير شكل العملة والتاريخ مع اللغة.
+
+**الأنابيب الجاهزة:** `upper` و`lower` و`capitalize` و`trim` و`truncate:n` و`currency:'USD'` و`number:digits` و`percent:digits` و`date:'short'|'medium'|'long'` و`time` و`ago` و`bytes` و`json` و`fallback:'قيمة'` و`join:sep` و`first` و`last` و`slice:a:b` و`reverse` و`sortBy:'key':'desc'` و`count`.
+
+**أنبوبك الخاص:** أي دالة في المكوّن تصلح أنبوبًا، وتتقدّم على الجاهز عند تطابق الاسم:
+
+```js
+// في سكربت المكوّن
+state name = 'ali'
+const wrap = (v, left = '«', right = '»') => left + v + right
+```
+```html
+<p>{ name | wrap }</p>        <!-- «ali» -->
+<p>{ name | wrap:'[':']' }</p> <!-- [ali] -->
+```
+
+ولتعريف أنبوب لكل التطبيق: `Kreftjs.pipe('shout', (v) => String(v).toUpperCase() + '!')`.
+
+> **تنبيه:** `a | b` كانت تعني عملية OR على مستوى البتات. إن كنت تستخدمها في قالب فاكتبها `(a | b)` داخل دالة، فالقالب الآن يفسّرها أنبوبًا.
+
+## 2) `k-match` و`k-case` و`k-default`
+
+بدل سلسلة `k-if` و`k-elif`:
+
+```html
+<div k-match="status">
+  <b k-case="'ok'">تم</b>
+  <i k-case="'wait', 'queued'">بالانتظار</i>   <!-- أكثر من قيمة -->
+  <u k-default>غير معروف</u>
+</div>
+```
+
+- المقارنة صارمة (`===`).
+- تُعرض أول حالة مطابقة فقط، و`k-default` للحالة التي لا يطابقها شيء (يوضع آخرًا).
+- الأبناء المباشرون فقط هم الحالات، ويعملون كما يعمل `k-if`: مكوّنات و`<template>` و`k-animate`.
+
+## 3) خصائص بأنواع
+
+اكتب النوع بصيغة TypeScript، وتحصل على تحذير أثناء التطوير عند قيمة خاطئة أو خاصية مطلوبة غائبة:
+
+```html
+prop tone: 'info' | 'warn' = 'info'   // قيم محددة، والافتراضي info
+prop label: string                     // مطلوبة: غيابها يحذّر
+prop count?: number                    // اختيارية
+prop items: string[] = []
+prop onSave: (id: number) => void
+```
+
+يُتحقق من: `string` و`number` و`boolean` و`null` و`undefined` و`object` و`Date` و`T[]` والدوال والقيم الحرفية (`'sm'` و`3` و`true`) والاتحاد بينها. أما أسماء أنواعك (`User`) و`any` و`unknown` فلا تُفحص.
+
+الخصائص التي لها قيمة افتراضية أو `?` أو تقبل `null`/`undefined` ليست مطلوبة. والنوع `number` أو `boolean` أو `string` يحوّل أيضًا القيمة المكتوبة نصًا في الوسم (`count="5"` تصبح `5`).
+
+## تمارين
+
+1. اعرض سعرًا بالدينار الكويتي وتاريخ إنشاء بصيغة `ago` في صفحة طلبات.
+2. حوّل سلسلة `k-if` من أربع حالات لحالة الطلب إلى `k-match`.
+3. أضف إلى مكوّن `Badge` الخاصية `prop tone: 'info' | 'warn' | 'danger' = 'info'` وجرّب `tone="loud"` لترى التحذير.

package/book/ar/README.md

@@ -2,7 +2,7 @@
 
 كتاب عملي لتتعلم **Kreft (`kreftjs`)**، الإطار التفاعلي ذو لغة المكوّنات `.kreft` والواجهة الخلفية المتكاملة على Node.js، وبناء تطبيقات الويب وسطح المكتب به.
 
-> **ملاحظة عن الدقة:** الأمثلة المتقدمة (الفصول 11 إلى 14) **جُرِّبت فعلًا**: شُغّل خادم Kreft، وأُرسلت طلبات حقيقية، وفُتحت الصفحات في متصفح. وما لم نستطع التحقق منه ذكرناه صراحة في موضعه. الإطار ما زال تجريبيًا (`0.0.x-beta`)، فراجع `docs/README.md` (بالإنجليزية) عند أي اختلاف مع إصدارك.
+> **ملاحظة عن الدقة:** الأمثلة المتقدمة (الفصول 11 إلى 20) **جُرِّبت فعلًا**: شُغّل خادم Kreft، وأُرسلت طلبات حقيقية، وفُتحت الصفحات في متصفح. وما لم نستطع التحقق منه ذكرناه صراحة في موضعه. الإطار ما زال تجريبيًا (`0.0.x-beta`)، فراجع `docs/README.md` (بالإنجليزية) عند أي اختلاف مع إصدارك.
 
 ## الفهرس
 
@@ -33,12 +33,21 @@
 
 15. [مرجع سريع وأخطاء شائعة ومصطلحات](15-appendix.md).
 
+### الجزء الرابع: أمثلة الخبراء
+
+16. [قوائم ضخمة بلا تباطؤ](16-virtual-list.md): النافذة الافتراضية لعرض 100,000 صف فما فوق.
+17. [مكوّن مركّب: قائمة اختيار ذكية](17-combobox.md): Combobox ببحث ولوحة مفاتيح وبوابة و`k-model`.
+18. [مزامنة بين التبويبات ودون اتصال](18-tabs-offline.md): حضور حيّ وطابور أوامر يرسل عند عودة الاتصال.
+19. [معالج متعدد الخطوات مع استئناف](19-wizard.md): مخزن محفوظ وتحقق لكل خطوة وحراسة للمسارات.
+20. [الأنابيب و`k-match` وأنواع الخصائص](20-pipes-match-props.md): صيغة أقصر وأوضح للقوالب والمكوّنات.
+
 ## كيف تقرأ هذا الكتاب؟
 
 - **مبتدئ:** الفصول 1 إلى 5 بالترتيب، ونفّذ التمارين في نهاية كل فصل.
 - **تعرف JavaScript وتريد تطبيقًا كاملًا:** 4 ثم 6 ثم 7 ثم 11 و12.
 - **تريد النشر:** 9 (وانتبه إلى قسم `<base>`).
 - **تريد سطح المكتب:** 10.
+- **تريد مستوى الخبير في الواجهة:** 16 إلى 20 بعد أن تتقن الفصول 2 و3 و4.
 
 ## ما الذي سنبنيه؟
 
@@ -48,6 +57,8 @@
 - متجر بسلة ودفع آمن لا يكرر الطلبات ولا يبيع ما نفد.
 - مكتبة مكوّنات (نافذة وجدول وتوجيهات).
 - لوحة أرقام حيّة وتقرير يومي مجدول.
+- قائمة افتراضية تعرض 100,000 صف بلا تباطؤ.
+- قائمة اختيار ذكية، ومزامنة حيّة بين التبويبات، ومعالج إعداد يستأنف بعد التحديث.
 
 ## تشغيل أمثلة الكتاب
 

package/docs/README.md

@@ -55,34 +55,34 @@ node --version      # v22.5.0 or higher
 
 ### Install the command
 
-Pick one way.
+Always ask npm for the newest version with `@latest`. Pick one way.
 
 **1. Once, for every project (recommended).** The `kreft` command then works in any folder (the package is called `kreftjs`):
 
 ```bash
-npm i -g kreftjs
+npm install -g kreftjs@latest
 ```
 
-**2. Without installing anything.** `npx` downloads Kreft, runs it and forgets it. Good for trying it out:
+**2. Inside one project.** The version is saved in the project's `package.json`, so everyone who clones the project, your server and your CI get the same one:
 
 ```bash
-npx kreftjs new my-app
+npm install -D kreftjs@latest
+npx kreftjs dev
 ```
 
-**3. Inside one project.** The command is saved in the project's `package.json`, so everyone who clones the project gets the same version, and so does your server or CI:
+**3. Without installing anything.** `npx` downloads Kreft, runs it and forgets it. Good for trying it out:
 
 ```bash
-npm i -D kreftjs
-npx kreftjs dev
+npx kreftjs@latest new my-app
 ```
 
 > [!NOTE]
-> The scripts of a new project (`npm run dev`, `build`, `serve` …) call `kreftjs`. With way 1 that is the global command. With way 3, npm finds it in the project's `node_modules` by itself. On a server where you did not install it globally, run `npm i -D kreftjs` in the project before `npm run build` or `npm run serve`.
+> The scripts of a new project (`npm run dev`, `build`, `serve` …) call `kreftjs`. With way 1 that is the global command. With way 2, npm finds it in the project's `node_modules` by itself. On a server where it is not installed globally, run `npm install -D kreftjs@latest` in the project before `npm run build` or `npm run serve`.
 
 ### Check that it works
 
 ```bash
-kreft --version     # for example 0.0.20-beta
+kreft --version     # for example 0.0.22-beta
 kreft about         # Kreft and Node.js versions, this project's settings and drivers
 kreft list          # every command your version has
 ```
@@ -100,7 +100,7 @@ installs colors and snippets for `.kreft` files in VS Code (also Cursor and VSCo
 ### Update
 
 ```bash
-npm i -g kreftjs@latest      # the command (or: npm i -D kreftjs@latest inside a project)
+npm install -g kreftjs@latest      # the command (or: npm install -D kreftjs@latest inside a project)
 cd my-app
 kreft update --check       # what would change
 kreft update --core        # refresh this app's kreftjs.js and type files (a backup is saved)
@@ -381,6 +381,7 @@ Modifiers: `.prevent` `.stop` `.self` `.once` `.capture` `.passive`. Keys: `.ent
 | Directive | What it does |
 |---|---|
 | `k-if` / `k-elif` / `k-else` | Adds or removes the element. |
+| `k-match="value"` + `k-case` / `k-default` on its children | Shows the child whose `k-case` equals the value. See [Choosing with k-match](#choosing-with-k-match). |
 | `k-each="item in list"` + `k-key="item.id"` | Repeats the element. Also `(item, i) in list`, `(value, key) in object`, `n in 10`. |
 | `k-model="name"` | Two-way binding for input, textarea, select, checkbox and radio. Modifiers `.trim` `.number` `.lazy`. |
 | `k-show` | Hides with CSS instead of removing. |
@@ -475,6 +476,62 @@ app.directive('focus', {
 <div k-tooltip:top={message}></div>   <!-- binding.arg = 'top', binding.value = message -->
 ```
 
+### Choosing with k-match
+
+When one value decides what to show, `k-match` reads better than a chain of `k-if` / `k-elif`:
+
+```html
+<div k-match="status">
+  <b k-case="'ok'">Done</b>
+  <i k-case="'wait', 'queued'">Waiting</i>
+  <u k-default>Unknown</u>
+</div>
+```
+
+- The comparison is strict (`===`). Several values in one `k-case` (separated by commas) mean "one of these".
+- Only the first matching case shows. `k-default` shows when none match; put it last.
+- The children are turned into `k-if` / `k-elif` / `k-else`, so components, `<template>` and `k-animate` work on them as usual.
+
+### Pipes
+
+Pass a value through a pipe with `|` to format it, instead of calling helper functions in the view:
+
+```html
+<p>{price | currency:'EUR'}</p>
+<p>{createdAt | ago}</p>
+<p>{title | capitalize | truncate:30}</p>
+<a title={name | upper}>{tags | join:' · '}</a>
+```
+
+- Arguments follow a colon (`truncate:30`, `currency:'EUR'`) or sit in parentheses (`number(2)`). Pipes run left to right.
+- `||`, `|=` and a `|` inside a string, a regular expression or brackets are not pipes.
+- Numbers, currency and dates follow the app's language (`Kreftjs.locale`).
+
+| Pipe | Result |
+|---|---|
+| `upper` `lower` `capitalize` `trim` | Text case and spaces. |
+| `truncate:n` | Cuts text to `n` characters and adds `…`. |
+| `currency:'USD'` | `$1,234.50`, in the current language. |
+| `number:digits` `percent:digits` | `1,234.5`, `45%` (0.45). |
+| `date:'short'` `time` | `short`, `medium` (default), `long`, `full`; or an `Intl.DateTimeFormat` options object. |
+| `ago` | `3 hours ago`, `in 2 days`. A date like `2026-11-05 15:39:58` from the Kreft database is read as UTC. |
+| `bytes` | `1.5 KB`. |
+| `json` | Pretty-printed JSON, for debugging. |
+| `fallback:'n/a'` | The value, or the fallback when it is empty. |
+| `join:sep` `first` `last` `slice:a:b` `reverse` `sortBy:'key':'desc'` `count` | Lists. |
+
+**Your own pipe.** Any function in the component works as a pipe, and wins over a built-in with the same name:
+
+```html
+const wrap = (value, left = '«', right = '»') => left + value + right
+
+<view><p>{name | wrap}</p> <p>{name | wrap:'[':']'}</p></view>
+```
+
+For the whole app: `Kreftjs.pipe('shout', (value) => String(value).toUpperCase() + '!')`.
+
+> `a | b` used to be a bitwise OR. In a view it is now a pipe; write bit operations inside a function in the script.
+
 ## Props, events and slots
 
 ### Using a component
@@ -516,6 +573,23 @@ prop admin = false
 
 The default's type decides how plain text attributes are read: `age="30"` becomes the number `30`, and `admin` with no value becomes `true`. A child cannot change a prop; send an event instead.
 
+### Typed props
+
+Write the type the way TypeScript does. A wrong value, or a missing required prop, warns while you develop (in `kreft dev` and in a built app's console):
+
+```html
+prop tone: 'info' | 'warn' = 'info'   // only these values; 'info' when not given
+prop label: string                     // required: leaving it out warns
+prop count?: number                    // optional
+prop items: string[] = []
+prop onSave: (id: number) => void
+```
+
+- Checked: `string` `number` `boolean` `null` `undefined` `object` `Date`, `T[]`, functions, literal values (`'sm'`, `3`, `true`) and unions of them. Your own type names (`User`), `any` and `unknown` are not checked.
+- A prop is required when it has no default, no `?` and its type has no `null` / `undefined`.
+- `number`, `boolean` and `string` also decide how a plain attribute is read: `count="5"` becomes `5`.
+
+
 ### Events: child to parent
 
 ```html
@@ -1217,10 +1291,36 @@ Generate one with `kreft make:controller PostController --api` (also `--model Po
 |---|---|
 | `req.input('name', default)`, `req.all()`, `req.only('a', 'b')`, `req.except(…)`, `req.has(…)`, `req.filled(…)` | Values from the body and the query. |
 | `req.boolean('x')`, `req.integer('page', 1)`, `req.string('q')` | A value in the right type. |
-| `await req.validate(rules)` | The same rules as `form()`, plus `unique:table,column` and `exists:table,column`. Returns only the checked fields, or answers `422`. |
+| `await req.validate(rules, messages, names)` | The same rules as `form()`, plus `unique:table,column` and `exists:table,column`. Returns only the checked fields, or answers `422`. `messages` are your own texts (`{ 'title.unique': 'That title is already used.' }`, or `{ unique: '…' }` for every field); `names` are nicer field names (`{ email: 'e-mail address' }`). |
 | `req.params`, `req.query`, `req.body`, `req.header('x')`, `req.bearerToken()`, `req.ip()`, `req.user` | The rest. |
 | `req.file('avatar').store('avatars')` | Saves an upload with a random name. |
 | `response(data, 201)`, `response(data).header('X', 'y')`, `abort(403, 'message')` | Answers. |
+| `response.stream('/path/video.mp4', { type, download, headers })` | Sends a file with byte ranges. See [Video and audio files](#video-and-audio-files). |
+
+### Video and audio files
+
+To serve a video or audio file, return `response.stream(path)` instead of reading the file yourself:
+
+```js
+const path = require('path')
+
+Route.get('/videos/:name', (req) =>
+  response.stream(path.join(__dirname, '../storage/videos', path.basename(req.params.name))))
+
+Route.get('/podcast/:id/download', (req) =>
+  response.stream('/var/media/episode.mp3', { download: true }))   // saved as a file instead of played
+```
+
+- **Seeking works.** The server answers `Range` requests with `206 Partial Content`, so a player can jump to any minute without downloading the rest, and Safari, which refuses to play video without ranges, plays it. A range that does not fit the file gets `416`.
+- **Only the needed bytes are read**, and reading stops when the viewer leaves or seeks elsewhere.
+- **Caching is built in.** The answer carries `ETag` and `Last-Modified`, so an unchanged file is answered with `304`. `HEAD` requests get the headers only.
+- **A missing file is a plain `404`**, not a crash.
+- Options: `type` (the media type; guessed from the extension for `mp4`, `webm`, `mov`, `mp3`, `m4a`, `ogg`, `wav`, `flac`, `m3u8`, `mpd`, `vtt` …), `download: true` (adds `Content-Disposition: attachment`), and `headers` (extra headers).
+
+> [!WARNING]
+> Never build the path straight from the request. Use `path.basename(...)` as above, or look the file up in your database, so nobody can ask for `../../.env`.
+
+`kreft dev` and `kreft serve` also send the static media files of your app (`.mp4`, `.webm`, `.mp3`, HLS playlists …) with ranges, so a `<video src="/intro.mp4" controls>` seeks without any code.
 
 ### Form requests, resources and policies
 
@@ -1276,6 +1376,8 @@ class Post extends Model {
 module.exports = Post
 ```
 
+**Always set `static fillable`.** Without it a model lets `create()` and `update()` set every column except `id`, so `Post.create(req.all())` would save `{ "is_admin": true }` from a visitor. The controllers made by `kreft make:controller --model` read only the `fillable` columns (`req.only(...Model.fillable)`) and stop with an error until you set it. Kreft prints a warning when a model without `fillable` is given a privilege-looking column (`is_admin`, `role`, `permissions` …).
+
 The table is the plural of the class name (`Post` is `posts`); set `static table = '…'` for another one.
 
 ### Querying
@@ -1756,7 +1858,7 @@ Apache only knows the files on disk, so without these rules `/docs` or any other
 > [!NOTE]
 > This hosts the front end only. Login, the database and everything under `/api` need the Node.js server, which Apache does not run.
 
-**A Node.js plan or a VPS.** Upload the whole project (without `node_modules`), not `dist/`. Add Kreft to its dependencies with `npm i kreftjs`, build with `npm run build`, and start the server with `npm run serve` (it reads the `PORT` your host sets). The generated `start` script runs the development server, so do not use it in production.
+**A Node.js plan or a VPS.** Upload the whole project (without `node_modules`), not `dist/`. Add Kreft to its dependencies with `npm install kreftjs@latest`, build with `npm run build`, and start the server with `npm run serve` (it reads the `PORT` your host sets). The generated `start` script runs the development server, so do not use it in production.
 
 
 On a VPS, keep it running with PM2 and put nginx in front of it for your domain and HTTPS:
@@ -1781,6 +1883,30 @@ server {
 Then `sudo certbot --nginx -d example.com` adds HTTPS. Set `APP_ENV=production` and a real `APP_KEY` in `.env` first, and read the [Production checklist](#production-checklist).
 
 
+### Publish the website (kreftjs.com)
+
+The Kreft website is the `demo/` app plus the `docs/` manual. Three commands make it, and a fourth puts it online:
+
+```bash
+npm install kreftjs@latest     # in a project that uses Kreft; in this repository, plain: npm install
+npm run build                  # writes the finished site to dist/kreftjs-com
+```
+
+Then upload what is *inside* `dist/kreftjs-com` (not the folder itself, and including the hidden `.htaccess`) to the folder kreftjs.com is served from, normally `public_html` (see [Upload to a host](#upload-to-a-host)). Open https://kreftjs.com and reload a page such as `/docs` to check that the clean addresses work.
+
+`npm run build` runs `kreft build demo --out dist/kreftjs-com --base / --include docs`. `--base /` makes every path start at the site's root, and `--include docs` copies the manual in. To look at the result before you upload it, run `npm run preview`.
+
+**Releasing a new version of the package.** This is done by the maintainer, before the site is built, so the site and the package agree:
+
+```bash
+npm test                       # the regression tests must pass
+npm version prerelease --preid=beta   # or: patch, minor (changes package.json and makes a git tag)
+npm publish --tag latest       # needs npm login; the package is then installed with kreftjs@latest
+npm run build                  # then upload dist/kreftjs-com as above
+```
+
+Check that people get it with `npm view kreftjs version` and a fresh `npm install -g kreftjs@latest`.
+
 ### Ready HTML for every page: `--prerender`
 
 ```bash
@@ -2165,10 +2291,80 @@ curl -H "Authorization: Bearer a-long-random-secret" -d '{"jsonrpc":"2.0","id":1
 > [!WARNING]
 > The MCP database tool can still read every other table. Use a database account with read-only access and no access to credentials, and keep the token out of version control.
 
+### Calling other MCP servers (client)
+
+Your app can also call tools on a remote MCP server over Streamable HTTP:
+
+```js
+const { Mcp } = require('kreftjs/server')
+
+const quran = await Mcp.connect('https://mcp.quran.ai')   // { headers: { Authorization: 'Bearer …' } } if needed
+const tools = await quran.tools()
+const verses = await quran.call('fetch_quran', { ayahs: '1:1-2' })
+await quran.close()
+```
+
+`call` returns the structured result (or the text, parsed as JSON when possible) and throws if the tool reports an error. Only `http(s)` URLs are accepted, redirects are refused, and a response over `maxBytes` (10 MB) is cut off. Never pass a URL a visitor typed: your server would fetch addresses of their choosing, including your internal network (SSRF). Use a fixed or allow-listed URL.
+
+## Running `kreft dev` outside a project
+
+`kreft dev` and `kreft serve` start only in a Kreft project: a folder with `index.html`, a `frontend/` folder, `.kreft` pages, a backend or a `kreftjs.config.json`. In any other folder (an empty one, your home folder) they stop and say so, instead of serving whatever is there. `kreft dev --force` serves the folder anyway. `kreft run dev` is not a command: inside a project use `kreft dev`, or `npm run dev`.
+
+## Kreft Shield
+
+Floods and scanners from one address can slow a server to a crawl. Turn on the Shield with one line in `.env` (changes apply without a restart):
+
+```
+SHIELD=true
+```
+
+For every visitor address (the same `req.ip()` that `throttle` uses, so set `TRUSTED_PROXIES` behind a proxy):
+
+| Protection | Default | Setting |
+|---|---|---|
+| Rate limit: over the limit answers `429` with `Retry-After` | 300 requests in 10 s | `SHIELD_MAX_REQUESTS`, `SHIELD_WINDOW_SEC` |
+| Probing counts more: `401`, `403`, `404` and `405` answers weigh 5 requests | 5 | `SHIELD_ERROR_WEIGHT` |
+| Concurrency: requests in flight at once from one address | 60 | `SHIELD_MAX_CONCURRENT` |
+| Ban: this many rate-limit hits within the strike window | 3 hits in 10 min | `SHIELD_STRIKES`, `SHIELD_STRIKE_WINDOW_MIN` |
+| Ban length, doubling at every repeat up to 24 h | 15 min | `SHIELD_BAN_MINUTES` |
+| Connections: open sockets from one address; extra ones are closed (stops slowloris floods that never finish a request) | 100 | `SHIELD_MAX_CONNECTIONS` |
+| Overload: when the event loop lags, limits shrink to a quarter | 300 ms lag | `SHIELD_MAX_LAG_MS` |
+
+IPv6 visitors are counted by their `/64` prefix, because one customer owns billions of addresses in it and could otherwise rotate through them.
+
+**Behind nginx, Caddy or a CDN, set `TRUSTED_PROXIES`.** Without it every visitor looks like the proxy: all users would share one limit and one ban, and a proxy on the same computer (`127.0.0.1`) is never limited at all. The Shield prints a warning when it sees `X-Forwarded-For` from an address that is not trusted.
+
+Never limited: addresses in `SHIELD_ALLOW="1.2.3.4,5.6.7.8"` and this computer (`127.0.0.1`, `::1`), unless `SHIELD_LOCAL=true` (use it to try the Shield on your own machine). A banned address is answered with a bare `429` before any work is done.
+
+```js
+const { Shield } = require('kreftjs/server')
+Shield.on('ban', (b) => Log.warning(`banned ${b.ip} for ${b.minutes} min: ${b.reason}`))
+Shield.bans()            // who is banned now
+Shield.unban('1.2.3.4')  // let an address back in
+Shield.ban('1.2.3.4', 60)
+Shield.status()          // counters, limits, event-loop lag
+```
+
+The MCP tool `shield_status` returns the same. Bans are kept in memory, so a restart clears them. The Shield protects the application; a flood that fills your network connection has to be stopped by a firewall or a CDN in front of the server.
+
 ## Memory watchdog
 
 Long-running servers can slowly collect memory. Start with `--gc` (or `AUTO_GC=1`) and Kreft samples the heap every 30 seconds (`AUTO_GC_INTERVAL_MS`). When it passes `AUTO_GC_THRESHOLD_MB`, Kreft clears its own caches and runs garbage collection. This is a safety net; find the leak if you see it often.
 
+The watchdog is a small memory manager:
+
+- **Adaptive.** A cleanup also runs when the heap keeps growing (more than `AUTO_GC_GROWTH_MB_PER_MIN`, default 20) while already above 60% of the threshold, not only after it passes the limit.
+- **Least-used first.** The in-memory cache (`CACHE_STORE=memory`) keeps at most `CACHE_MEMORY_MAX` entries (default 5000) and, under pressure, drops expired and least recently used entries instead of everything. Register your own cache with `onMemoryPressure('name', (fraction) => dropped)`.
+- **Leak hint.** After each real GC (needs `--gc`) Kreft records the heap that remains. If it keeps rising by `AUTO_GC_LEAK_RISE_MB` (default 20) over several collections, it reports a suspected leak. `writeHeapSnapshot()` saves a `.heapsnapshot` for Chrome DevTools to show what holds the memory.
+- **Alerts.** `onMemoryAlert((alert) => …)` is called when memory is still high after `AUTO_GC_ALERT_AFTER` cleanups in a row (default 3), or a leak is suspected, at most once per 10 minutes. Without a listener the alert is printed as a warning.
+- **Report.** `getMemoryReport()` returns the samples, trend, GC and eviction counts, leak state and alerts as JSON; the MCP tool `memory_report` returns the same.
+
+```js
+const { getMemoryReport, onMemoryAlert } = require('kreftjs/server')
+onMemoryAlert((a) => Log.warning(a.message))
+Route.get('/admin/memory', () => getMemoryReport()).middleware('auth')
+```
+
 # Security
 
 ## Security overview
@@ -2351,7 +2547,7 @@ Set these in `.env` (never commit it). Variables that start with `PUBLIC_` are c
 |---|---|
 | `.kreft` keywords | `state` `derive` `action` `when` `watch` `on` `prop` `event` `use` `share` `receive` `import` `saved` `load` `layout` |
 | In the script | `send` `props` `bus` `store` `$route` `$router` `tick` and every `Kreft` function |
-| In the view | `{expr}` `attr={expr}` `@event` `k-if` `k-elif` `k-else` `k-each` `k-key` `k-model` `k-show` `k-text` `k-html` `k-ref` `k-skip` `k-once` `k-memo` `k-animate` `{for}` |
+| In the view | `{expr}` `attr={expr}` `@event` `k-if` `k-elif` `k-else` `k-each` `k-key` `k-match` `k-case` `k-default` `k-model` `k-show` `k-text` `k-html` `k-ref` `k-skip` `k-once` `k-memo` `k-animate` `{for}` |
 | App | `Kreftjs.app(rootOrPath)` then `.component()` `.directive()` `.share()` `.use()` `.mount()` `.unmount()` |
 | Data | `store` (`$patch` `$reset` `$watch`) `state` `signal` `derived` `readonly` `saved` `storage` |
 | Reacting | `watch` `effect` `tick` `onCleanup` `onReady` `onUpdate` `onShow` `onHide` `onDestroy` |

package/editors/sublime/Comments.tmPreferences

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>scope</key>
+	<string>text.html.kreft</string>
+	<key>settings</key>
+	<dict>
+		<key>shellVariables</key>
+		<array>
+			<dict>
+				<key>name</key>
+				<string>TM_COMMENT_START</string>
+				<key>value</key>
+				<string>&lt;!-- </string>
+			</dict>
+			<dict>
+				<key>name</key>
+				<string>TM_COMMENT_END</string>
+				<key>value</key>
+				<string> --&gt;</string>
+			</dict>
+		</array>
+	</dict>
+</dict>
+</plist>

package/editors/sublime/Component.sublime-snippet

@@ -0,0 +1,20 @@
+<snippet>
+	<content><![CDATA[
+state ${1:count} = ${2:0}
+
+action ${3:add}() {
+  ${1:count}++
+}
+
+<view>
+  <button @click={${3:add}}>{${1:count}}</button>
+</view>
+
+<style scoped>
+  $0
+</style>
+]]></content>
+	<tabTrigger>kreftjs</tabTrigger>
+	<scope>text.html.kreft</scope>
+	<description>A new .kreft component</description>
+</snippet>

package/editors/sublime/Kreft.sublime-syntax

@@ -0,0 +1,39 @@
+%YAML 1.2
+---
+name: Kreft
+scope: text.html.kreft
+version: 2
+file_extensions:
+  - kreft
+  - kreftjs
+first_line_match: ^\s*<view\b
+
+contexts:
+  main:
+    # <view>, <script> and <style> blocks are HTML (with JS and CSS inside)
+    - match: (?i)(?=<view\b)
+      embed: scope:text.html.basic
+      embed_scope: text.html.embedded.kreft
+      escape: (?i)(?<=</view>)
+    - match: (?i)(?=<script\b)
+      embed: scope:text.html.basic
+      embed_scope: text.html.embedded.kreft
+      escape: (?i)(?<=</script>)
+    - match: (?i)(?=<style\b)
+      embed: scope:text.html.basic
+      embed_scope: text.html.embedded.kreft
+      escape: (?i)(?<=</style>)
+    - match: <!--
+      scope: punctuation.definition.comment.begin.html
+      push: html-comment
+    # everything else at the top level is the component's JavaScript
+    - match: '^\s*(layout|prop|state|saved|derive|action|load|watch|when|on|event|use|share|receive)\b'
+      captures:
+        1: keyword.control.kreft storage.type.kreft
+    - include: scope:source.js
+
+  html-comment:
+    - meta_scope: comment.block.html
+    - match: -->
+      scope: punctuation.definition.comment.end.html
+      pop: true

package/editors/sublime/LICENSE

@@ -0,0 +1,95 @@
+Copyright 2026 Maxamuud Xuseen
+
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/editors/sublime/README.md

@@ -0,0 +1,7 @@
+# Kreft for Sublime Text
+
+Syntax for `.kreft` / `.kreftjs` files (extends Sublime's built-in HTML syntax, so `<script>` is JavaScript and `<style>` is CSS), comment toggling, and snippets.
+
+Install: copy this folder to `Packages/Kreft` (Preferences > Browse Packages...) and reopen a `.kreft` file.
+
+Limit: Kreft-only keywords (`state`, `action`, ...) get no special color yet.

package/editors/sublime/action.sublime-snippet

@@ -0,0 +1,10 @@
+<snippet>
+	<content><![CDATA[
+action ${1:name}(${2}) {
+  $0
+}
+]]></content>
+	<tabTrigger>action</tabTrigger>
+	<scope>text.html.kreft</scope>
+	<description>A function the view can call</description>
+</snippet>

package/editors/sublime/derive.sublime-snippet

@@ -0,0 +1,8 @@
+<snippet>
+	<content><![CDATA[
+derive ${1:name} = ${2:expression}
+]]></content>
+	<tabTrigger>derive</tabTrigger>
+	<scope>text.html.kreft</scope>
+	<description>A value worked out from others</description>
+</snippet>