@helfy/helfy 0.0.6 → 0.0.8

package/README.md

@@ -1,52 +1,72 @@
 # Helfy
 
-Helfy -- TypeScript UI-фреймворк с декоратор-ориентированным API, кастомным JSX и fine-grained reactivity.
+Helfy — a TypeScript UI framework with a decorator-oriented API, custom JSX, and fine-grained reactivity.
 
-Компоненты описываются классами с декоратором `@View`, состояние управляется через `@state` и `@observable`, а шаблоны используют расширенный JSX с директивами `@if`, `@for`, `@else`. Реактивность построена на signals (аналог SolidJS): `render()` вызывается один раз, а последующие обновления DOM происходят точечно — только для тех узлов, которые читают изменившийся signal.
+Components are defined as classes with the `@View` decorator, state is managed via `@state` and `@observable`, and templates use extended JSX with `@if`, `@for`, and `@else` directives. Reactivity is built on signals (similar to SolidJS): `render()` runs once, and subsequent DOM updates are granular — only nodes that read the changed signal are updated.
 
-## Содержание
+## Table of contents
 
-- [Установка](#установка)
-- [Компоненты](#компоненты)
-  - [Базовый компонент](#базовый-компонент)
+- [Installation](#installation)
+- [Components](#components)
+  - [Basic component](#basic-component)
   - [Props](#props)
-  - [Локальное состояние (@state)](#локальное-состояние-state)
-  - [Вложенные компоненты](#вложенные-компоненты)
-  - [Монтирование в DOM](#монтирование-в-dom)
-  - [Привязка к DOM и компонентам (@ref)](#привязка-к-dom-и-компонентам-ref)
-  - [Двустороннее связывание (@bind)](#двустороннее-связывание-bind)
-  - [Формы (@Form, @field, @field в JSX)](#формы-form-field-field-в-jsx)
-- [Шаблонные директивы](#шаблонные-директивы)
+  - [Local state (@state)](#local-state-state)
+  - [Nested components](#nested-components)
+  - [DOM mounting](#dom-mounting)
+  - [DOM and component refs (@ref)](#dom-and-component-refs-ref)
+  - [Two-way binding (@bind)](#two-way-binding-bind)
+  - [Forms (@Form, @field, @field in JSX)](#forms-form-field-field-in-jsx)
+- [Template directives](#template-directives)
   - [@if / @elseif / @else](#if--elseif--else)
   - [@for](#for)
   - [@empty](#empty)
 - [State Management](#state-management)
-  - [Создание Store](#создание-store)
-  - [Подписка через @observe](#подписка-через-observe)
-  - [Контекст хранилищ](#контекст-хранилищ)
-- [Логирование (@logger)](#логирование-logger)
+  - [Creating a Store](#creating-a-store)
+  - [Subscribing with @observe](#subscribing-with-observe)
+  - [Store context](#store-context)
+- [Logging (@logger)](#logging-logger)
 - [Context & DI](#context--di)
-  - [Провайдер (@Context, @provide)](#провайдер-context-provide)
-  - [Потребитель (@ctx)](#потребитель-ctx)
-  - [Реактивные поля](#реактивные-поля)
-  - [Опциональная инжекция](#опциональная-инжекция)
-  - [DI Container](#di-container-конструкторный-инжект)
+  - [Provider (@Context, @provide)](#provider-context-provide)
+  - [Consumer (@ctx)](#consumer-ctx)
+  - [Reactive fields](#reactive-fields)
+  - [Optional injection](#optional-injection)
+  - [DI Container](#di-container-constructor-injection)
 - [JSX](#jsx)
-  - [Атрибуты](#атрибуты)
-  - [События](#события)
-  - [Стили](#стили)
-  - [CSS-классы](#css-классы)
+  - [Attributes](#attributes)
+  - [Events](#events)
+  - [Styles](#styles)
+  - [CSS classes](#css-classes)
 - [API](#api)
 
 ---
 
-## Установка
+## Installation
+
+### Creating a new project (helfy-create)
+
+Quick start — create a project with a single command:
+
+```bash
+npx helfy-create my-app
+cd my-app
+npm run dev
+```
+
+Without a project name (creates `helfy-app`):
+
+```bash
+npx helfy-create
+```
+
+The `--skip-install` option — create without running `npm install` (e.g. for offline use or custom registry).
+
+### Adding to an existing project
 
 ```bash
 npm install @helfy/helfy
 ```
 
-или в `package.json`:
+Or in `package.json`:
 
 ```json
 {
@@ -58,11 +78,11 @@ npm install @helfy/helfy
 
 ### Build setup
 
-Babel-плагин автоматически запускает DI-сканер перед трансформацией (pre-скрипты в `package.json` не нужны). Сканер генерирует `.helfy/di-tokens.ts`, `.helfy/di-registry.ts`. Добавьте `.helfy` в `.gitignore`.
+The Babel plugin runs the DI scanner before transformation (no pre-scripts in `package.json` needed). The scanner generates `.helfy/di-tokens.ts` and `.helfy/di-registry.ts`. Add `.helfy` to `.gitignore`.
 
 ### Babel
 
-В `.babelrc` достаточно одного пресета:
+A single preset in `.babelrc` is enough:
 
 ```json
 {
@@ -70,11 +90,11 @@ Babel-плагин автоматически запускает DI-сканер
 }
 ```
 
-Пресет включает: JSX runtime, TypeScript, legacy-декораторы, class properties, babel-plugin-transform-typescript-metadata, **helfy-di** (compile-time DI для `@Injectable<IX>()`, автоинъекция регистрации при `createApp`, трансформация `@logger()` → `@logger("<ClassName>")`).
+The preset includes: JSX runtime, TypeScript, legacy decorators, class properties, babel-plugin-transform-typescript-metadata, **helfy-di** (compile-time DI for `@Injectable<IX>()`, auto-registration at `createApp`, `@logger()` → `@logger("<ClassName>")` transformation).
 
 ### Webpack
 
-Для обработки директив (`@if`, `@for`, `@ref`, `@bind`, `@field`) в `.tsx` файлах подключить loader:
+To process directives (`@if`, `@for`, `@ref`, `@bind`, `@field`) in `.tsx` files, add the loader:
 
 ```javascript
 {
@@ -88,7 +108,7 @@ Babel-плагин автоматически запускает DI-сканер
 
 ### TypeScript
 
-В `tsconfig.json` указать:
+In `tsconfig.json` set:
 
 ```json
 {
@@ -96,20 +116,20 @@ Babel-плагин автоматически запускает DI-сканер
     "jsx": "preserve",
     "experimentalDecorators": true,
     "emitDecoratorMetadata": true,
-    "plugins": [{ "name": "@helfy/helfy/ts-plugin" }]
+    "plugins": [{ "name": "@helfy/helfy-ts-plugin" }]
   }
 }
 ```
 
-Плагин `@helfy/helfy/ts-plugin` даёт поддержку директив `@if`, `@for`, `@ref`, `@bind`, `@field` в IDE (автодополнение, типизация, переход к определению). Идёт в комплекте с пакетом helfy.
+The `@helfy/helfy-ts-plugin` plugin provides IDE support for `@if`, `@for`, `@ref`, `@bind`, `@field` directives (autocomplete, typing, go-to-definition). Install separately: `npm install @helfy/helfy-ts-plugin`.
 
 ---
 
-## Компоненты
+## Components
 
-### Базовый компонент
+### Basic component
 
-Компонент -- это класс с декоратором `@View` и методом `render()`, возвращающим JSX:
+A component is a class with the `@View` decorator and a `render()` method that returns JSX:
 
 ```tsx
 import { View } from "@helfy/helfy";
@@ -126,19 +146,19 @@ class Hello {
 }
 ```
 
-Декоратор `@View` автоматически:
-- вызывает `render()` **один раз** и монтирует результат в DOM-фрагмент
-- добавляет свойство `view` (ссылка на корневой DOM-элемент)
-- оборачивает `this.props` в реактивный Proxy (каждый prop — signal)
-- настраивает fine-grained эффекты: при изменении signal обновляется только конкретный DOM-узел, а не весь компонент
+The `@View` decorator automatically:
+- calls `render()` **once** and mounts the result into a DOM fragment
+- adds a `view` property (reference to the root DOM element)
+- wraps `this.props` in a reactive Proxy (each prop is a signal)
+- configures fine-grained effects: when a signal changes, only the specific DOM node that reads it is updated, not the entire component
 
-> **Важно:** При наследовании `@View` нужно указывать и на дочернем классе. Без этого не будут работать `@ctx`, `scheduleUpdate` и обновление DOM.
+> **Important:** When inheriting from `@View`, apply the decorator on the child class as well. Otherwise `@ctx`, `scheduleUpdate`, and DOM updates will not work.
 
 ### Props
 
-Props передаются через конструктор. Декоратор `@View` оборачивает `this.props` в реактивный Proxy — каждый prop становится signal. Это означает, что при изменении props родителем обновляются только те DOM-узлы, которые их читают, без полного перерендера компонента.
+Props are passed via the constructor. The `@View` decorator wraps `this.props` in a reactive Proxy — each prop becomes a signal. This means that when the parent updates props, only the DOM nodes that read them are updated, without a full re-render.
 
-> **Важно:** Не деструктуризируйте `this.props` в `render()`. Обращайтесь к полям напрямую через `this.props.field` — это обеспечивает корректную подписку на signals.
+> **Important:** Do not destructure `this.props` in `render()`. Access fields directly via `this.props.field` — this ensures correct signal subscription.
 
 ```tsx
 import { View } from "@helfy/helfy";
@@ -166,18 +186,17 @@ class Button {
 }
 ```
 
-Использование:
+Usage:
 
 ```tsx
-<Button label="Нажми" onClick={() => console.log('clicked')} />
+<Button label="Click" onClick={() => console.log('clicked')} />
 ```
 
-При изменении props родителем `updateProps()` обновляет соответствующие signals через `batch()`. Fine-grained эффекты, созданные Babel-плагином (`createReactiveChild`), отслеживают эти signals и точечно обновляют DOM.
+When the parent updates props, only the DOM nodes that read the changed props are updated.
 
-### Локальное состояние (@state)
+### Local state (@state)
 
-Декоратор `@state` делает поле реактивным — под капотом каждое поле — это signal из `createSignal()`.  
-При изменении значения обновляются только те DOM-узлы и эффекты, которые читают это поле (fine-grained). Полный перерендер компонента не происходит:
+The `@state` decorator makes a field reactive. When its value changes, only the DOM nodes and effects that read it are updated (fine-grained). The component is not fully re-rendered:
 
 ```tsx
 import { View, state } from "@helfy/helfy";
@@ -187,7 +206,7 @@ class Counter {
     @state private count = 0;
 
     increment() {
-        this.count++; // обновит только узлы, читающие count
+        this.count++; // updates only nodes that read count
     }
 
     decrement() {
@@ -206,13 +225,13 @@ class Counter {
 }
 ```
 
-Можно объявить несколько `@state`-полей. Каждое из них независимо триггерит обновление только тех узлов DOM, которые его читают.
+You can declare multiple `@state` fields. Each independently triggers updates only in the DOM nodes that read it.
 
-Signals‑примитивы (`createSignal`, `createEffect`, `createComputed`, `batch`, `onCleanup`) также экспортируются из `helfy` и могут использоваться напрямую, но в большинстве случаев достаточно `@state`, `@computed` и `@effect`.
+Signal primitives (`createSignal`, `createEffect`, `createComputed`, `batch`, `onCleanup`) are also exported from `helfy` and can be used directly, but in most cases `@state`, `@computed`, and `@effect` are sufficient.
 
-### Вложенные компоненты
+### Nested components
 
-Компоненты используются в JSX как теги. Props передаются как атрибуты:
+Components are used in JSX as tags. Props are passed as attributes:
 
 ```tsx
 import { View } from "@helfy/helfy";
@@ -230,20 +249,31 @@ class App {
 }
 ```
 
-### Монтирование в DOM
+### DOM mounting
+
+Typical bootstrap is via `createApp()`: an instance is created, `attach(root)` is called internally, and the `onAttached()` hook runs after insertion into the document.
+
+```typescript
+import { createApp } from "@helfy/helfy";
+
+createApp({ root: document.getElementById("root")! })
+  .router({ routes })
+  .mount(App);
+```
 
-Корневой компонент монтируется через `attach()`, чтобы вызвать хук `onAttached()` (после вставки в document):
+For scenarios without routing:
 
 ```typescript
-const app = new App();
-app.attach(document.getElementById('root'));
+createApp({ root: document.getElementById("root")! }).mount(App);
 ```
 
-### Привязка к DOM и компонентам (@ref)
+Manual mounting (without `createApp`): `const app = new App(); app.attach(root)`.
 
-Декоратор `@ref` помечает поле для получения ссылки на DOM-элемент или экземпляр компонента. В JSX используется директива `@ref(this.имяПоля)`. Доступ к ссылке возможен после `onMount()`. Для операций вроде `focus()`, требующих элемент в document, используйте `onAttached()`.
+### DOM and component refs (@ref)
 
-**Для компонентов** — родитель получает прокси с доступом только к методам, помеченным `@expose`. Это позволяет явно определить публичный API компонента.
+The `@ref` decorator marks a field to receive a reference to a DOM element or component instance. In JSX use the `@ref(this.fieldName)` directive. The reference is available after `onMount()`. For operations like `focus()` that require the element in the document, use `onAttached()`.
+
+**For components** — the parent receives a proxy with access only to methods marked with `@expose`. This lets you explicitly define the component's public API.
 
 ```tsx
 import { View, ref, expose } from "@helfy/helfy";
@@ -266,7 +296,7 @@ class Form {
     @ref private input!: Input;
 
     onAttached() {
-        this.input.focus();  // доступен только помеченный метод
+        this.input.focus();  // only the exposed method is available
     }
 
     render() {
@@ -275,15 +305,15 @@ class Form {
 }
 ```
 
-- DOM-элементы по `@ref` передаются как есть
-- Компоненты с `@expose` — родитель видит только помеченные методы
-- Компоненты без `@expose` — передаётся экземпляр целиком (обратная совместимость)
+- DOM elements via `@ref` are passed as-is
+- Components with `@expose` — parent sees only the exposed methods
+- Components without `@expose` — the full instance is passed (backward compatibility)
 
-При условном рендере (`@if`) ссылка обнуляется при удалении элемента. Запрещено использовать `@ref` и `@state` на одном поле.
+With conditional rendering (`@if`), the ref is cleared when the element is removed. Do not use `@ref` and `@state` on the same field.
 
-### Двустороннее связывание (@bind)
+### Two-way binding (@bind)
 
-Директива `@bind` — синтаксический сахар для двусторонней привязки значения поля `@state` к элементу формы. Синтаксис: `@bind(expr)` — круглые скобки, как у `@ref`. Компилятор автоматически генерирует пару `value`/`checked` и обработчик события.
+The `@bind` directive is syntactic sugar for two-way binding of a `@state` field to a form element. Syntax: `@bind(expr)` — parentheses, like `@ref`. The compiler generates the `value`/`checked` pair and event handler.
 
 ```tsx
 import { View, state } from "@helfy/helfy";
@@ -301,8 +331,8 @@ class LoginForm {
                 <input @bind(this.email) type="email" />
                 <input @bind(this.isActive) type="checkbox" />
                 <select @bind(this.priority)>
-                    <option value="low">Низкий</option>
-                    <option value="high">Высокий</option>
+                    <option value="low">Low</option>
+                    <option value="high">High</option>
                 </select>
             </form>
         );
@@ -310,24 +340,24 @@ class LoginForm {
 }
 ```
 
-Трансформация по типу элемента:
+Transformation by element type:
 
-| Элемент | Атрибут | Событие |
-|---------|---------|---------|
+| Element | Attribute | Event |
+|---------|-----------|-------|
 | `input[text|email|password|...]` | `value` | `oninput` |
 | `input[checkbox|radio]` | `checked` | `onchange` |
 | `select` | `value` | `onchange` |
 | `textarea` | `value` | `oninput` |
 
-Поле должно быть помечено `@state` для реактивного обновления UI. Для union-типов (например, `TodoPriority`) используется приведение `as typeof expr` — типобезопасность сохраняется.
+The field must be marked with `@state` for reactive UI updates. For union types (e.g. `TodoPriority`), use `as typeof expr` — type safety is preserved.
 
-**Кастомные компоненты:** для привязки к компоненту с пропом `value` используется именованный биндинг `@bind:value(expr)`:
+**Custom components:** for binding to a component with a `value` prop, use named binding `@bind:value(expr)`:
 
 ```tsx
-// Родитель
-<Input @bind:value(this.title) placeholder="Заголовок" />
+// Parent
+<Input @bind:value(this.title) placeholder="Title" />
 
-// Компонент Input с @binded("value")
+// Input component with @binded("value")
 @View
 class Input {
   @binded("value") private bindedVal!: string;
@@ -338,11 +368,11 @@ class Input {
 }
 ```
 
-### Формы (@Form, @field, @field в JSX)
+### Forms (@Form, @field, @field in JSX)
 
-Централизованное управление формами с валидацией через контекст: `@Form` — класс контекста формы, `@field` — декоратор полей (создаёт `FieldState`), `@useForm` — инжект формы в компонент. JSX-директива `@field(expr)` подключает инпут к `FieldState` одной строкой.
+Centralized form handling with validation via context: `@Form` — form context class, `@field` — field decorator (creates `FieldState`), `@useForm` — injects the form into a component. The JSX directive `@field(expr)` connects an input to `FieldState` in one line.
 
-**FormContext** — класс с `@Form` и полями `@field`:
+**FormContext** — a class with `@Form` and `@field` fields:
 
 ```tsx
 import { Form, field, logger, type FieldState, type ILogger } from "@helfy/helfy";
@@ -361,7 +391,7 @@ export class LoginFormContext {
   rememberMe!: FieldState<boolean>;
 
   validateAll(): boolean {
-    // проверка полей, установка field.error
+    // validate fields, set field.error
     return true;
   }
 
@@ -375,9 +405,25 @@ export class LoginFormContext {
 }
 ```
 
-**FieldState** содержит `value`, `isDirty`, `isTouched`, `error`, `isValid`. При изменении `value`/`error`/`isTouched` компоненты с `@useForm` перерендериваются.
+**FieldState** has `value`, `isDirty`, `isTouched`, `error`, `isValid`. When `value`/`error`/`isTouched` changes, components with `@useForm` re-render.
+
+**Form provider** — the parent component wraps the form in context:
+
+```tsx
+// LoginPage.tsx
+@View
+export class LoginPage {
+  render() {
+    return (
+      <LoginFormContext>
+        <LoginForm />
+      </LoginFormContext>
+    );
+  }
+}
+```
 
-**Компонент формы** — инжект через `@useForm`, рендер через провайдер:
+**Form component** — inject via `@useForm`, access fields via `this.form`:
 
 ```tsx
 import { View, useForm } from "@helfy/helfy";
@@ -389,79 +435,79 @@ export class LoginForm {
 
   render() {
     return (
-      <LoginFormContext>
-        <form onsubmit={(e: Event) => { e.preventDefault(); this.form.submit(); }}>
-          <input @field(this.form.email) type="email" class="input" />
-          {this.form.email.isTouched && this.form.email.error && (
-            <span class="error">{this.form.email.error}</span>
-          )}
-          <input @field(this.form.password) type="password" class="input" />
-          <input @field(this.form.rememberMe) type="checkbox" id="remember" />
-          <label for="remember">Запомнить меня</label>
-          <button type="submit">Войти</button>
-        </form>
-      </LoginFormContext>
+      <form onsubmit={(e: Event) => { e.preventDefault(); this.form.submit(); }}>
+        <input @field(this.form.email) type="email" class="input" />
+        {this.form.email.isTouched && this.form.email.error && (
+          <span class="error">{this.form.email.error}</span>
+        )}
+        <input @field(this.form.password) type="password" class="input" />
+        <input @field(this.form.rememberMe) type="checkbox" id="remember" />
+        <label for="remember">Remember me</label>
+        <button type="submit">Sign in</button>
+      </form>
     );
   }
 }
 ```
 
-**JSX-директива `@field(expr)`** — одна директива заменяет `@bind` + `onblur` + `class` для ошибок + `aria-invalid`. Компилятор генерирует:
+Wrapper components (TextField, CheckboxField, etc.) accept `field` as a prop: `<TextField field={this.form.email} label="Email" />` and use `<input @field(this.props.field) />` internally.
+
+**JSX directive `@field(expr)`** — one directive replaces `@bind` + `onblur` + error `class` + `aria-invalid`. The compiler generates:
 
-- `value`/`checked` и `oninput`/`onchange`
+- `value`/`checked` and `oninput`/`onchange`
 - `onblur` → `expr.isTouched = true`
-- `class` — объединение с существующим; при `expr.isTouched && expr.error` добавляется `input-error`
+- `class` — merged with existing; when `expr.isTouched && expr.error` adds `input-error`
 - `aria-invalid={expr.isTouched && expr.error ? "true" : "false"}`
 
-Поддерживаются `input` (text, email, password, checkbox, radio), `select`, `textarea`. Класс `.input-error` можно задать в глобальных стилях (например, `@apply border-red-500` в Tailwind).
+Supports `input` (text, email, password, checkbox, radio), `select`, `textarea`. The `.input-error` class can be defined in global styles (e.g. `@apply border-red-500` in Tailwind).
 
 ---
 
-## Шаблонные директивы
+## Template directives
 
-Helfy расширяет JSX директивами `@if`, `@elseif`, `@else`, `@for`, `@empty`. Компилятор трансформирует их в вызовы `$._if()`, `$._ifelse()`, `$._forin()` на этапе сборки.
+Helfy extends JSX with `@if`, `@elseif`, `@else`, `@for`, and `@empty` directives.
 
 ### @if / @elseif / @else
 
-Условный рендеринг:
+Conditional rendering:
 
 ```tsx
 render() {
     return (
         <div>
             @if (this.count > 0) {
-                <span>Положительное: {this.count}</span>
+                <span>Positive: {this.count}</span>
             }
         </div>
     );
 }
 ```
 
-Цепочка условий:
+Condition chains:
 
 ```tsx
 render() {
     return (
         <div>
             @if (this.status === 'loading') {
-                <span>Загрузка...</span>
+                <span>Loading...</span>
             } @elseif (this.status === 'error') {
-                <span>Ошибка!</span>
+                <span>Error!</span>
             } @else {
-                <span>Данные загружены</span>
+                <span>Data loaded</span>
             }
         </div>
     );
 }
 ```
 
-Вложенные условия:
+Nested conditions:
 
 ```tsx
 @if (this.isVisible) {
     <div>
         @if (this.count > 10) {
-            <span>Больше десяти</span>
+            <span>More than ten</span>
         }
     </div>
 }
@@ -469,7 +515,7 @@ render() {
 
 ### @for
 
-Итерация по массиву. Синтаксис: `@for (item of array)` или `@for (item, index of array)`.
+Array iteration. Syntax: `@for (item of array)` or `@for (item, index of array)`.
 
 ```tsx
 @state private items = ['apple', 'banana', 'cherry'];
@@ -485,7 +531,7 @@ render() {
 }
 ```
 
-`track` задает ключ для оптимизации DOM-диффинга (аналог `key` в React):
+`track` sets the key for DOM diffing optimization (like `key` in React):
 
 ```tsx
 @for (user of this.users; track user.id) {
@@ -495,13 +541,13 @@ render() {
 
 ### @empty
 
-Блок `@empty` после `@for` рендерится, когда массив пуст:
+The `@empty` block after `@for` renders when the array is empty:
 
 ```tsx
 @for (item of this.items; track item) {
     <div>{item}</div>
 } @empty {
-    <span>Список пуст</span>
+    <span>List is empty</span>
 }
 ```
 
@@ -509,9 +555,9 @@ render() {
 
 ## State Management
 
-### Создание Store
+### Creating a Store
 
-Store -- глобальное реактивное хранилище. Создается классом с декоратором `@Store`, реактивные поля помечаются `@observable`:
+A Store is a global reactive store. Create a class with the `@Store` decorator; reactive fields use `@observable`:
 
 ```typescript
 import { Store, observable } from "@helfy/helfy";
@@ -523,7 +569,7 @@ class UserStore {
 
     login(name: string) {
         this.name = name;
-        this.isLoggedIn = true; // подписчики name и isLoggedIn уведомлены
+        this.isLoggedIn = true; // subscribers of name and isLoggedIn are notified
     }
 
     logout() {
@@ -535,15 +581,15 @@ class UserStore {
 export default UserStore;
 ```
 
-Декоратор `@Store` добавляет классу:
-- `subscribe(field, callback)` -- подписка на изменение поля, возвращает функцию отписки
-- `unsubscribe(field, callback)` -- отписка
+The `@Store` decorator adds:
+- `subscribe(field, callback)` — subscribe to field changes, returns unsubscribe function
+- `unsubscribe(field, callback)` — unsubscribe
 
-Декоратор `@observable` превращает поле в реактивное свойство с getter/setter. При записи нового значения все подписчики уведомляются.
+The `@observable` decorator turns a field into a reactive property with getter/setter. On write, all subscribers are notified.
 
-### Подписка через @observe
+### Subscribing with @observe
 
-Декоратор `@observe` связывает поле компонента с полем store. При изменении значения в store компонент автоматически перерендерится:
+The `@observe` decorator binds a component field to a store field. When the store value changes, the component re-renders:
 
 ```tsx
 import { View, observe } from "@helfy/helfy";
@@ -562,9 +608,9 @@ class Header {
         return (
             <header>
                 @if (this.isLoggedIn) {
-                    <span>Привет, {this.userName}!</span>
+                    <span>Hello, {this.userName}!</span>
                 } @else {
-                    <span>Войдите в систему</span>
+                    <span>Sign in</span>
                 }
             </header>
         );
@@ -572,11 +618,11 @@ class Header {
 }
 ```
 
-Тип поля берется из store через lookup-тип (`UserStore['name']`), что дает полную типобезопасность.
+The field type is inferred from the store via lookup type (`UserStore['name']`), giving full type safety.
 
-### Контекст хранилищ
+### Store context
 
-Рекомендуется создать единый контекст для всех store:
+Create a single context for all stores:
 
 ```typescript
 import UserStore from "./UserStore";
@@ -590,26 +636,26 @@ class Stores {
 export default Stores;
 ```
 
-Использование в компонентах:
+Usage in components:
 
 ```tsx
 import Stores from "./StoreContext";
 
-// подписка через декоратор
+// subscribe via decorator
 @observe(Stores.userStore, 'name')
 private userName: string;
 
-// прямой вызов метода store
+// direct store method call
 Stores.userStore.login("Alice");
 ```
 
 ---
 
-## Логирование (@logger)
+## Logging (@logger)
 
-Декоратор `@logger` инжектирует логгер в классы View, Context, Store и Injectable. Имя класса подставляется на этапе компиляции (Babel-плагин), что сохраняет читаемые имена даже при минификации.
+The `@logger` decorator injects a logger into View, Context, Store, and Injectable classes. The class name is set at compile time (Babel plugin), keeping readable names even after minification.
 
-### Использование
+### Usage
 
 ```tsx
 import { View, logger, type ILogger } from "@helfy/helfy";
@@ -626,22 +672,22 @@ class TodoInput {
 }
 ```
 
-**Варианты:**
-- `@logger()` — имя класса подставляется на compile-time как `<ClassName>`, формат и цвет зависят от типа класса
-- `@logger("my-tag")` — кастомный тег, серый цвет
+**Variants:**
+- `@logger()` — class name is set at compile-time as `<ClassName>`, format and color depend on class type
+- `@logger("my-tag")` — custom tag, gray color
 
-### Формат и цвет тегов по типу класса
+### Tag format and color by class type
 
-| Тип | Формат | Цвет |
-|-----|--------|------|
-| View (компоненты) | `<TodoInput>` | skyblue |
-| Injectable (сервисы) | `TodoValidateService()` | pink |
+| Type | Format | Color |
+|------|--------|-------|
+| View (components) | `<TodoInput>` | skyblue |
+| Injectable (services) | `TodoValidateService()` | pink |
 | Context | `{TodoContext}` | khaki |
 | Form | `[LoginFormContext]` | bright blue |
 | Store | `TodoStore[]` | lime green |
-| Кастомный `@logger("...")` | как указано | gray |
+| Custom `@logger("...")` | as specified | gray |
 
-### API логгера
+### Logger API
 
 ```typescript
 interface ILogger {
@@ -649,13 +695,13 @@ interface ILogger {
   info(message: string, meta?: Record<string, unknown>): void;
   warn(message: string, meta?: Record<string, unknown>): void;
   error(messageOrError: string | Error, meta?: Record<string, unknown>): void;
-  withContext(ctx: string): ILogger;  // дочерний логгер с доп. префиксом
+  withContext(ctx: string): ILogger;  // child logger with extra prefix
 }
 ```
 
-### DI и транспорты
+### DI and transports
 
-`LoggerService` регистрируется под `ILoggerToken` при `registerAllServices`. Можно подключить кастомные транспорты (Sentry, файл и т.д.), реализующие `ILogTransport`:
+`LoggerService` is registered under `ILoggerToken` via `registerAllServices`. Custom transports (Sentry, file, etc.) implementing `ILogTransport` can be wired up:
 
 ```typescript
 import { LoggerService, ConsoleTransport, ILoggerToken } from "@helfy/helfy";
@@ -668,17 +714,17 @@ createApp({ root })
   .mount(App);
 ```
 
-Без зарегистрированного логгера в контейнере используется fallback с выводом в `console`.
+Without a registered logger in the container, a fallback that logs to `console` is used.
 
 ---
 
 ## Context & DI
 
-Helfy поддерживает иерархический Context и Dependency Injection: провайдер оборачивает поддерево в JSX, а дочерние компоненты получают значения через `@ctx`. Это удобно для темы, форм, роутинга и других общих зависимостей.
+Helfy supports hierarchical Context and Dependency Injection: a provider wraps a subtree in JSX, and child components receive values via `@ctx`. Useful for theme, forms, routing, and other shared dependencies.
 
-### Провайдер (@Context, @provide)
+### Provider (@Context, @provide)
 
-Класс с декоратором `@Context` — не-рендерящий провайдер: он не имеет `render()` и рендерит только своих детей. Поля с `@provide` становятся доступны потребителям ниже по дереву.
+A class with the `@Context` decorator is a non-rendering provider: it has no `render()` and only renders its children. Fields with `@provide` are available to consumers down the tree.
 
 ```tsx
 import { Context, provide } from "@helfy/helfy";
@@ -697,7 +743,7 @@ export class ThemeContext {
 }
 ```
 
-Использование в JSX — обёртка вокруг поддерева:
+Usage in JSX — wrap a subtree:
 
 ```tsx
 <ThemeContext>
@@ -706,11 +752,11 @@ export class ThemeContext {
 </ThemeContext>
 ```
 
-Фреймворк рендерит только детей `ThemeContext`; сам провайдер не создаёт DOM-узлов.
+The framework only renders the children of `ThemeContext`; the provider itself does not create DOM nodes.
 
-### Потребитель (@ctx)
+### Consumer (@ctx)
 
-Компонент с `@View` может получать значение контекста через `@ctx`:
+A component with `@View` can receive context values via `@ctx`:
 
 ```tsx
 import { View, ctx } from "@helfy/helfy";
@@ -724,14 +770,14 @@ class ThemeToggle {
   render() {
     return (
       <button onclick={this.theme.toggle}>
-        {this.theme.mode === "dark" ? "Светлая тема" : "Тёмная тема"}
+        {this.theme.mode === "dark" ? "Light theme" : "Dark theme"}
       </button>
     );
   }
 }
 ```
 
-Можно инжектировать только поле контекста:
+You can inject only a context field:
 
 ```tsx
 @View
@@ -740,20 +786,31 @@ class ModeDisplay {
   private mode!: TThemeMode;
 
   render() {
-    return <span>Текущая тема: {this.mode}</span>;
+    return <span>Current theme: {this.mode}</span>;
   }
 }
 ```
 
-Поиск провайдера идёт вверх по дереву (`_parentView`); используется ближайший провайдер с нужным ключом.
+Provider lookup goes up the tree (`_parentView`); the nearest provider with the matching key is used.
 
-### Реактивные поля
+### Reactive fields
 
-`@provide({ reactive: true })` делает поле реактивным: при изменении все потребители перерендериваются (под капотом используется `subscribe`). Для методов достаточно `@provide()` без `reactive`.
+`@provide({ reactive: true })` makes a field reactive: when it changes, all consumers re-render. For methods, `@provide()` without `reactive` is enough.
 
-### Опциональная инжекция
+**Computed fields** — getters with `@provide({ computed: true, deps: ["field1", "field2"] })` recompute when dependencies change and trigger consumer re-renders:
 
-Третий аргумент `@ctx` — опции `{ optional?, defaultValue? }`:
+```tsx
+@provide({ computed: true, deps: ["todos", "filter"] })
+get filteredTodos(): Todo[] {
+  return this.filter === "active"
+    ? this.todos.filter(t => !t.completed)
+    : this.todos;
+}
+```
+
+### Optional injection
+
+The third argument of `@ctx` — options `{ optional?, defaultValue? }`:
 
 ```tsx
 @ctx(ThemeContext, { optional: true })
@@ -763,15 +820,15 @@ private theme?: ThemeContext;
 private mode = "light";
 ```
 
-Без провайдера в дереве `optional: true` даёт `undefined`; `defaultValue` используется, когда провайдера нет.
+With no provider in the tree, `optional: true` yields `undefined`; `defaultValue` is used when the provider is absent.
 
-### DI Container (конструкторный инжект)
+### DI Container (constructor injection)
 
-Helfy поддерживает DI-контейнер для глобальных сервисов с **compile-time** магией: сервисы помечаются `@Injectable<IX>()`, потребители указывают только тип в конструкторе — без `@inject` и явных токенов.
+Helfy supports a DI container for global services with **compile-time** magic: services are marked with `@Injectable<IX>()`, consumers only specify the type in the constructor — no `@inject` or explicit tokens.
 
-**Конвенция:** последний параметр конструктора — props от родителя; предшествующие параметры резолвятся из контейнера или из @Context по дереву.
+**Convention:** the last constructor parameter is props from the parent; preceding parameters are resolved from the container or from @Context up the tree.
 
-**Сервис** — обязательно `@Injectable<IX>()` (интерфейс в generic):
+**Service** — must use `@Injectable<IX>()` (interface in generic):
 
 ```typescript
 export interface ITodoValidateService {
@@ -784,7 +841,7 @@ export class TodoValidateService implements ITodoValidateService {
 }
 ```
 
-**Потребитель** — только тип в конструкторе (плагин подставляет токен):
+**Consumer** — only the type in the constructor (plugin injects the token):
 
 ```tsx
 @View
@@ -796,7 +853,7 @@ class TodoInput {
 }
 ```
 
-**Bootstrap** — регистрация DI подключается автоматически при `createApp` (плагин подставляет `.useDI(registerAllServices)` в цепочку):
+**Bootstrap** — DI registration is attached automatically at `createApp` (plugin injects `.useDI(registerAllServices)` in the chain):
 
 ```typescript
 createApp({ root: document.getElementById("root")! })
@@ -804,9 +861,9 @@ createApp({ root: document.getElementById("root")! })
   .mount(App);
 ```
 
-Сканер вызывается Babel-плагином перед трансформацией, находит все `@Injectable<IX>()`, генерирует `.helfy/di-tokens.ts` и `.helfy/di-registry.ts`.
+The scanner is run by the Babel plugin before transformation, finds all `@Injectable<IX>()`, and generates `.helfy/di-tokens.ts` and `.helfy/di-registry.ts`.
 
-**Fallback** — для ручной настройки доступны `.configureContainer()`, `@inject(token)`, `@Injectable(token)`:
+**Fallback** — for manual setup: `.configureContainer()`, `@inject(token)`, `@Injectable(token)`:
 
 ```typescript
 createApp({ root })
@@ -818,38 +875,38 @@ createApp({ root })
   .mount(App);
 ```
 
-Опционально: передать свой контейнер через `.container(myContainer)` или `createApp({ root, container })`.
+Optionally: pass a custom container via `.container(myContainer)` or `createApp({ root, container })`.
 
-`@Context` и контейнер сосуществуют: Context — для tree-scoped значений (тема, роутер), Container — для глобальных сервисов.
+`@Context` and the container coexist: Context is for tree-scoped values (theme, router), Container for global services.
 
 ---
 
 ## JSX
 
-Helfy использует кастомный JSX runtime (`@helfy/helfy/jsx-runtime`). JSX транслируется в вызовы `jsx()` / `jsxs()`, которые строят виртуальное представление DOM.
+Helfy uses a custom JSX runtime (`@helfy/helfy/jsx-runtime`). JSX is translated to `jsx()` / `jsxs()` calls that build a virtual DOM representation.
 
-### Атрибуты
+### Attributes
 
-Стандартные HTML-атрибуты передаются напрямую:
+Standard HTML attributes are passed through:
 
 ```tsx
-<input type="text" placeholder="Введите имя" />
+<input type="text" placeholder="Enter name" />
 <img src="/logo.png" alt="Logo" />
 <div id="container" class="wrapper"></div>
 ```
 
-### События
+### Events
 
-Обработчики событий передаются через атрибуты в **нижнем регистре** (`onclick`, `oninput`, а не `onClick`):
+Event handlers use **lowercase** attributes (`onclick`, `oninput`, not `onClick`):
 
 ```tsx
 <button onclick={() => this.increment()}>+</button>
 <input oninput={(e) => this.handleInput(e)} />
 ```
 
-### Стили
+### Styles
 
-Инлайн-стили передаются объектом с camelCase-ключами:
+Inline styles use an object with camelCase keys:
 
 ```tsx
 <div style={{
@@ -858,26 +915,26 @@ Helfy использует кастомный JSX runtime (`@helfy/helfy/jsx-run
     padding: '8px 16px',
     borderRadius: '4px'
 }}>
-    Стилизованный блок
+    Styled block
 </div>
 ```
 
-### CSS-классы
+### CSS classes
 
-Атрибут `class` принимает строку или массив с условными классами:
+The `class` attribute accepts a string or an array with conditional classes:
 
 ```tsx
-// строка
+// string
 <div class="container">...</div>
 
 // CSS Modules
 import styles from './App.module.css';
 <div class={styles.wrapper}>...</div>
 
-// условные классы через массив
+// conditional classes via array
 <div class={[
     styles.cell,
-    [styles.active, this.isActive],     // применяется если this.isActive === true
+    [styles.active, this.isActive],     // applied when this.isActive === true
     [styles.disabled, this.isDisabled],
 ]}>...</div>
 ```
@@ -886,116 +943,44 @@ import styles from './App.module.css';
 
 ## API
 
-### Декораторы
-
-| Декоратор | Область | Описание |
-|-----------|---------|----------|
-| `@View` | Класс | Превращает класс в компонент с `render()`, `view`, `update()` |
-| `@state` | Поле | Локальное состояние компонента на базе signals (запись обновляет только этот компонент) |
-| `@Store` | Класс | Добавляет `subscribe`/`unsubscribe` и реактивность `@observable`-полей |
-| `@observable` | Поле | Делает поле store реактивным -- запись уведомляет подписчиков |
-| `@observe(store, field)` | Поле | Связывает поле компонента с полем store |
-| `@Context` | Класс | Не-рендерящий провайдер контекста; рендерит только детей |
-| `@provide()` / `@provide({ reactive: true })` | Поле | Помечает поле как доступное для `@ctx` (reactive — потребители перерендериваются) |
-| `@ctx(ContextClass)` / `@ctx(ContextClass, field)` | Поле | Инжектирует контекст или поле контекста из ближайшего провайдера вверх по дереву |
-| `@Injectable<IX>()` / `@Injectable<IX>('singleton' \| 'transient' \| 'scoped')` / `@Injectable(token)` | Класс | Помечает класс как injectable. Scope в (): `'singleton'` (по умолчанию), `'transient'`, `'scoped'`. Fallback: `@Injectable(token)` с Symbol/строкой |
-| `@inject(token)` | Параметр конструктора | Задаёт токен для параметра (fallback; при `@Injectable<IX>()` плагин подставляет токен автоматически) |
-| `@logger()` / `@logger("tag")` | Поле | Инжектирует ILogger. Без аргумента — compile-time имя класса и цвет по типу (View/Context/Store/Injectable). С аргументом — кастомный тег (серый) |
-| `@ref` | Поле | Помечает поле для получения ссылки на DOM или компонент (использовать с `@ref(this.имяПоля)` в JSX) |
-| `@binded(name)` | Поле | Связывает поле с биндингом `@bind:name` от родителя (для кастомных компонентов) |
-| `@bind(expr)` / `@bind:name(expr)` | JSX | Двустороннее связывание с `@state` полем (value/checked + oninput/onchange). Для компонентов: `@bind:value(expr)` |
-| `@Form` | Класс | Контекст формы с полями `@field` |
-| `@field(options)` | Поле FormContext | Создаёт FieldState для поля формы (value, isTouched, error, isDirty) |
-| `@useForm(FormContext)` | Поле | Инжектирует форму в компонент с подпиской на изменения полей |
-| `@field(expr)` | JSX | Подключает инпут к FieldState: value/checked + onblur + error class + aria-invalid |
-
-### Экспорты пакета
+### Decorators
+
+| Decorator | Scope | Description |
+|-----------|-------|-------------|
+| `@View` | Class | Turns a class into a component with `render()`, `view`, `update()` |
+| `@state` | Field | Component local state on signals (write updates only this component) |
+| `@Store` | Class | Adds `subscribe`/`unsubscribe` and `@observable` field reactivity |
+| `@observable` | Field | Makes a store field reactive — write notifies subscribers |
+| `@observe(store, field)` | Field | Binds a component field to a store field |
+| `@Context` | Class | Non-rendering context provider; renders only children |
+| `@provide()` / `@provide({ reactive: true })` / `@provide({ computed: true, deps })` | Field | Marks a field as available to `@ctx`. `reactive` — consumers re-render on change; `computed` + `deps` — for getters |
+| `@ctx(ContextClass)` / `@ctx(ContextClass, field)` | Field | Injects context or a context field from the nearest provider up the tree |
+| `@Injectable<IX>()` / `@Injectable<IX>('singleton' \| 'transient' \| 'scoped')` / `@Injectable(token)` | Class | Marks a class as injectable. Scope in (): `'singleton'` (default), `'transient'`, `'scoped'`. Fallback: `@Injectable(token)` with Symbol/string |
+| `@inject(token)` | Constructor param | Sets the token for the parameter (fallback; with `@Injectable<IX>()` the plugin injects it automatically) |
+| `@logger()` / `@logger("tag")` | Field | Injects ILogger. No arg — compile-time class name and color by type (View/Context/Store/Injectable). With arg — custom tag (gray) |
+| `@ref` | Field | Marks a field to receive a DOM or component reference (use with `@ref(this.fieldName)` in JSX) |
+| `@expose` | Method | Makes a method available to the parent when using `@ref` on a component (without `@expose` the parent gets the full instance) |
+| `@binded(name)` | Field | Binds a field to `@bind:name` from the parent (for custom components) |
+| `@bind(expr)` / `@bind:name(expr)` | JSX | Two-way binding with `@state` field (value/checked + oninput/onchange). For components: `@bind:value(expr)` |
+| `@Form` | Class | Form context with `@field` fields |
+| `@field(options)` | FormContext field | Creates FieldState for a form field (value, isTouched, error, isDirty) |
+| `@useForm(FormContext)` | Field | Injects the form into a component with subscription to field changes |
+| `@field(expr)` | JSX | Connects an input to FieldState: value/checked + onblur + error class + aria-invalid |
+
+### Routing (SPA)
+
+Helfy includes a lightweight SPA router. When you call `createApp().router({ routes }).mount(App)`, the framework automatically wraps the app in `RouterContext`, so you don't need to wrap your App manually:
 
-```typescript
-import {
-  $,               // утилиты рендеринга ($._if, $._ifelse, $._forin, $._slot, $._callSlot)
-  View,            // декоратор @View
-  state,           // декоратор @state (signal-backed локальное состояние)
-  Store,           // декоратор @Store
-  observable,      // декоратор @observable
-  observe,         // декоратор @observe
-  computed,        // @computed для Store/@Context/@View (getter-based)
-  effect,          // @effect для реактивных сайд-эффектов во View
-  Context,         // декоратор @Context
-  provide,         // декоратор @provide
-  ctx,             // декоратор @ctx (поле, Context)
-  Container,       // DI-контейнер
-  Injectable,      // декоратор @Injectable
-  inject,          // декоратор @inject (параметр конструктора)
-  createViewInstance,
-  setRootContainer,
-  getRootContainer,
-  ref,             // декоратор @ref
-  binded,          // декоратор @binded (для компонентов с @bind:value)
-  Form,            // декоратор @Form (контекст формы)
-  field,           // декоратор @field (поле FormContext)
-  useForm,         // декоратор @useForm (инжект формы)
-  type FieldState,
-  type FieldOptions,
-  StoreBase,       // базовый класс Store (для расширения)
-  Subscriber,      // тип callback-подписчика
-  Router,          // ядро роутера (Router)
-  RouterContext,   // контекст роутера для дерева компонентов
-  RouterView,      // компонент, рендерящий текущий маршрут
-  Link,            // SPA-ссылка
-  DefaultNotFound, // fallback-компонент 404 (используется RouterView при отсутствии слота)
-  path,            // @path() — декоратор для pathname
-  search,          // @search() — декоратор для query-параметров
-  params,          // @params() — декоратор для route-параметров
-  router,          // @router() — декоратор для API роутера
-  logger,          // @logger() — декоратор для ILogger
-  LoggerService,   // реализация ILogger (DI)
-  ConsoleTransport,
-  ILoggerToken,
-  // primitives для fine-grained reactivity
-  createSignal,
-  createEffect,
-  createComputed,
-  batch,
-  onCleanup,
-  type Signal,
-  type SignalGetter,
-  type SignalSetter,
-  type EffectDisposer,
-  type RouteConfig,
-  type RouterLocation,
-  type ILogger,
-  type ILogTransport,
-  type LogLevel,
-} from "@helfy/helfy";
+```tsx
+// index.ts
+createApp({ root: document.getElementById("root")! })
+  .router({ routes })
+  .mount(App);
 ```
 
-### Subpath-экспорты
-
-| Путь | Назначение |
-|------|------------|
-| `helfy` | Основной API (декораторы, $, типы) |
-| `@helfy/helfy/router` | Тот же API роутера, но отдельным entry (для tree-shaking) |
-| `@helfy/helfy/jsx-runtime` | JSX runtime (`jsx`, `jsxs`) |
-| `@helfy/helfy/compiler/helfy-loader` | Webpack-loader для директив `@if`/`@for`/`@ref`/`@bind`/`@field` |
-| `@helfy/helfy/babel-preset` | Babel-пресет (JSX, TypeScript, декораторы) |
-
-### Роутинг (SPA)
-
-Helfy включает лёгкий SPA‑роутер, построенный на `Context & DI`:
-
 ```tsx
-import {
-  View,
-  RouterContext,
-  RouterView,
-  Link,
-  type RouteConfig,
-  type RouterLocation,
-  ctx,
-} from "@helfy/helfy";
-
-// Конфиг маршрутов
+import { View, RouterView, Link, path, type RouteConfig } from "@helfy/helfy";
+
 const routes: RouteConfig[] = [
   { path: "/", component: HomePage },
   { path: "/analytics", component: AnalyticsPage },
@@ -1007,45 +992,34 @@ const routes: RouteConfig[] = [
 class App {
   render() {
     return (
-      <RouterContext routes={routes}>
-        <Layout>
-          @slot.sidebar() {<Sidebar />}
-          @slot.content() {<RouterView />}
-        </Layout>
-      </RouterContext>
+      <Layout>
+        @slot.sidebar() {<Sidebar />}
+        @slot.content() {<RouterView />}
+      </Layout>
     );
   }
 }
 
 @View
 class Sidebar {
-  @ctx(RouterContext, "location")
-  private location!: RouterLocation;
+  @path()
+  private pathname!: string;
 
   render() {
-    const pathname = this.location.pathname;
-    const isHome = pathname === "/";
-    const isAnalytics = pathname.startsWith("/analytics");
+    const isHome = this.pathname === "/";
+    const isAnalytics = this.pathname.startsWith("/analytics");
 
     return (
       <nav>
-        <Link
-          to="/"
-          label="Главная"
-          class={isHome ? "font-bold" : ""}
-        />
-        <Link
-          to="/analytics"
-          label="Аналитика"
-          class={isAnalytics ? "font-bold" : ""}
-        />
+        <Link to="/" label="Home" class={isHome ? "font-bold" : ""} />
+        <Link to="/analytics" label="Analytics" class={isAnalytics ? "font-bold" : ""} />
       </nav>
     );
   }
 }
 ```
 
-Типичный компонент‑страница может использовать утилитарные декораторы роутера:
+A typical page component can use router decorators:
 
 ```tsx
 import { View, path, search, params, router, type RouterAPI } from "@helfy/helfy";
@@ -1072,7 +1046,7 @@ class DebugPage {
         <pre>params: {JSON.stringify(this.routeParams)}</pre>
         <pre>query: {JSON.stringify(this.query)}</pre>
         <button onclick={() => this.rtr.push("/analytics")}>
-          Перейти в аналитику
+          Go to analytics
         </button>
       </section>
     );
@@ -1080,14 +1054,7 @@ class DebugPage {
 }
 ```
 
-Под капотом:
-
-- `Router` использует `history.pushState/replaceState` и `popstate` для синхронизации с URL.
-- `RouterContext` хранит реактивное `location` (`@provide({ reactive: true })`), так что `@ctx(RouterContext, "location")` и декораторы `@path/@search/@params/@router` автоматически триггерят перерендер компонентов при смене маршрута.
-- `RouterView` сопоставляет текущий `pathname` с `RouteConfig` (в том числе с параметрами `:id` и вложенными маршрутами) и рендерит нужный `@View`‑класс. При отсутствии совпадения показывается `DefaultNotFound` или содержимое слота `@slot.notFound`.
-- `Link` перехватывает `click`, не перезагружает страницу и вызывает `router.push/replace`, сохраняя поведение обычных ссылок (`href` остаётся).
-
-**Кастомная страница 404.** Оберните `RouterView` и переопределите слот `notFound`:
+**Custom 404 page.** Wrap `RouterView` and override the `notFound` slot:
 
 ```tsx
 @View
@@ -1102,35 +1069,35 @@ class AppRouter {
     );
   }
 }
-``` 
+```
 
-### Жизненный цикл компонента
+### Component lifecycle
 
-1. `constructor(props)` -- создание экземпляра, `this.props` оборачивается в реактивный Proxy
-2. `render()` -- возврат JSX (**вызывается один раз** при монтировании; Babel-плагин оборачивает выражения в `createReactiveChild` для fine-grained обновлений)
-3. `mount()` -- первичный рендер JSX в DOM-фрагмент
-4. `onMount()` -- хук после первого монтирования (опциональный)
-5. `onAttached()` -- хук после вставки в document (опциональный). Вызывается при `attach(parent)`.
-6. `update()` -- структурное обновление (при смене корневого компонента, например при роутинге). Для одного и того же дочернего компонента обновляются только signals через `updateProps`
-7. `updateProps(newProps)` -- обновление prop-signals через `batch()` (fine-grained, без полного перерендера)
+1. `constructor(props)` — instance creation, `this.props` wrapped in reactive Proxy
+2. `render()` — returns JSX (**called once** on mount)
+3. `mount()` — initial JSX render to DOM fragment
+4. `onMount()` — hook after first mount (optional)
+5. `onAttached()` — hook after insertion into document (optional). Called on `attach(parent)`.
+6. `update()` — structural update (e.g. on route change). For the same child component, only signals are updated via `updateProps`
+7. `updateProps(newProps)` — updates prop signals (fine-grained, no full re-render)
 
 #### onMount vs onAttached
 
 | | `onMount()` | `onAttached()` |
 |---|---|---|
-| **Когда** | Сразу после `mount()`, дерево построено, рефы назначены | После `attach(parent)`, элемент в document |
-| **Элемент в document** | Может быть ещё нет (корень в fragment) | Да |
-| **Рефы** | Доступны | Доступны |
+| **When** | Right after `mount()`, tree built, refs assigned | After `attach(parent)`, element in document |
+| **Element in document** | May not be yet (root in fragment) | Yes |
+| **Refs** | Available | Available |
 
-**`onMount()`** — для инициализации, не требующей document:
-- Подписки на store/observable/сервисы
-- Настройка внутреннего состояния
-- Добавление обработчиков (работают и на detached-узлах)
+**`onMount()`** — for initialization that doesn't need the document:
+- Subscriptions to store/observable/services
+- Internal state setup
+- Adding handlers (works on detached nodes too)
 
-**`onAttached()`** — для операций, требующих элемент в document:
+**`onAttached()`** — for operations that require the element in the document:
 - `focus()`, `scrollIntoView()`
-- `getBoundingClientRect()`, замер layout
-- Любые DOM API, работающие только с подключённым узлом
+- `getBoundingClientRect()`, layout measurement
+- Any DOM API that only works on attached nodes
 
 ```tsx
 @View
@@ -1138,62 +1105,22 @@ class SearchInput {
   @ref private input!: HTMLInputElement;
 
   onMount() {
-    this.store.subscribe(this.handleChange);  // подписка — document не нужен
+    this.store.subscribe(this.handleChange);  // subscription — document not needed
   }
 
   onAttached() {
-    this.input.focus();  // фокус — нужен document
+    this.input.focus();  // focus — needs document
   }
 }
 ```
 
-### Утилиты рендеринга ($)
-
-Компилятор трансформирует директивы в вызовы `$`, но их можно использовать и напрямую.
-
-**Статические** (условие вычисляется один раз):
-
-```tsx
-import { $ } from "@helfy/helfy";
-
-render() {
-    return (
-        <div>
-            {$._if(this.visible, <span>Видно</span>)}
-            {$._ifelse(this.count > 0,
-                <span>Положительное</span>,
-                <span>Отрицательное или ноль</span>
-            )}
-            {$._forin(this.items, (item, index) => (
-                <div $_key={item.id}>{index}: {item.name}</div>
-            ))}
-        </div>
-    );
-}
-```
-
-**Реактивные** (условие и ветки — thunks, пересчитываются при изменении signals):
-
-```tsx
-{$._rIf(() => this.visible, () => <span>Видно</span>)}
-{$._rIfElse(() => this.count > 0,
-    () => <span>Положительное</span>,
-    () => <span>Отрицательное или ноль</span>
-)}
-{$._rForin(() => this.items, (item, index) => (
-    <div $_key={item.id}>{index}: {item.name}</div>
-))}
-```
-
-Компилятор автоматически выбирает реактивный вариант (`_rIf`, `_rIfElse`, `_rForin`) при генерации кода из директив `@if` / `@for`.
-
-### Слоты (content projection)
+### Slots (content projection)
 
-Helfy поддерживает именованные слоты с fallback‑содержимым и переопределением в дочерних компонентах.
+Helfy supports named slots with fallback content and override in child components.
 
-#### Провайдер слота (`@View`‑компонент)
+#### Slot provider (`@View` component)
 
-Слоты объявляются прямо в JSX через директиву `@slot:имя(...)` внутри `render()`:
+Slots are declared in JSX via the `@slot:name(...)` directive inside `render()`:
 
 ```tsx
 import { View } from "@helfy/helfy";
@@ -1203,24 +1130,24 @@ class AppLayout {
     render() {
         return (
             <section class="layout">
-                {/* Именованный слот header с fallback-разметкой */}
-                @slot:header({ title: "Список задач" }) fallback {
+                {/* Named slot header with fallback markup */}
+                @slot:header({ title: "Task list" }) fallback {
                     <header class="mb-4">
                         <h1 class="text-2xl font-bold text-gray-900">
-                            Список задач
+                            Task list
                         </h1>
                     </header>
                 }
 
-                {/* Именованный слот content с fallback и директивой @if внутри */}
+                {/* Named slot content with fallback and @if inside */}
                 @slot:content({ store: this.props.store, filtered: this.props.filtered, hasTodos: this.props.hasTodos }) fallback {
                     @if (this.props.hasTodos) {
                         <section class="pt-3 border-t border-gray-200 text-sm text-gray-600">
                             <p class="mb-1">
-                                Всего задач: {this.props.store.todos.length}, активных: {this.props.store.activeCount},
-                                завершённых: {this.props.store.completedCount}
+                                Total: {this.props.store.todos.length}, active: {this.props.store.activeCount},
+                                completed: {this.props.store.completedCount}
                             </p>
-                            <p>Фильтрованных к показу: {this.props.filtered.length}</p>
+                            <p>Filtered: {this.props.filtered.length}</p>
                         </section>
                     }
                 }
@@ -1230,15 +1157,15 @@ class AppLayout {
 }
 ```
 
-Правила для провайдера:
+Provider rules:
 
-- `@slot:header({ ... })` — объявляет именованный слот `header` и вызывает его.
-- Блок `fallback { ... }` (опциональный) задаёт разметку по умолчанию, если слот не переопределён.
-- Внутри `fallback` можно использовать директивы `@if`, `@for` и обычный JSX.
+- `@slot:header({ ... })` — declares the named slot `header` and invokes it.
+- The `fallback { ... }` block (optional) defines default markup when the slot is not overridden.
+- Inside `fallback` you can use `@if`, `@for`, and regular JSX.
 
-#### Потребитель слота (override в JSX)
+#### Slot consumer (override in JSX)
 
-Переопределение слота в дочернем компоненте делается через `@slot.имя(...) { ... }` внутри JSX‑детей:
+Override a slot in a child component via `@slot.name(...) { ... }` inside JSX children:
 
 ```tsx
 @View
@@ -1254,20 +1181,20 @@ class TodoApp {
                 filtered={filtered}
                 hasTodos={this.hasTodos}
             >
-                {/* Переопределяем слот header */}
+                {/* Override header slot */}
                 @slot.header({ title }) {
                     <header class="mb-5">
                         <h1 class="mb-4 text-2xl font-bold text-gray-900">
-                            Задачи ({title})
+                            Tasks ({title})
                         </h1>
                         <TodoInput
-                            placeholder="Добавить задачу…"
+                            placeholder="Add task…"
                             onSubmit={(text) => store.add(text)}
                         />
                     </header>
                 }
 
-                {/* Переопределяем слот content, внутри можно использовать @if/@for */}
+                {/* Override content slot, @if/@for allowed inside */}
                 @slot.content({ store, filtered, hasTodos }) {
                     @if (hasTodos) {
                         <section class="pt-3 border-t border-gray-200">
@@ -1293,8 +1220,8 @@ class TodoApp {
 }
 ```
 
-Кратко по синтаксису:
+Syntax summary:
 
-- `@slot:имя({ props }) fallback { FallbackJSX }` — объявление и вызов слота в провайдере.
-- `@slot.имя({ ctx }) { OverrideJSX }` — переопределение слота в потребителе.
-- Внутри `FallbackJSX` и `OverrideJSX` поддерживаются все директивы (`@if`, `@for`, `@empty`) и обычный JSX.
+- `@slot:name({ props }) fallback { FallbackJSX }` — declare and invoke the slot in the provider.
+- `@slot.name({ ctx }) { OverrideJSX }` — override the slot in the consumer.
+- All directives (`@if`, `@for`, `@empty`) and regular JSX work inside `FallbackJSX` and `OverrideJSX`.