@helfy/helfy 0.0.7 → 0.0.9

package/README.md

@@ -1,50 +1,54 @@
 # 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)
+  - [Architecture layers (Store, Service, UseCase)](#state-management)
+  - [Creating a Store](#creating-a-store-store)
+  - [Infrastructure services](#infrastructure-services-service)
+  - [Business use cases](#business-use-cases-usecase)
+  - [Accessing Store and UseCase from components](#accessing-store-and-usecase-from-components)
+  - [Store context (optional)](#store-context-optional)
+- [Logging (@logger)](#logging-logger)
 - [Context & DI](#context--di)
-  - [Провайдер (@Context, @provide)](#провайдер-context-provide)
-  - [Потребитель (@ctx)](#потребитель-ctx)
-  - [Реактивные поля](#реактивные-поля)
-  - [Опциональная инжекция](#опциональная-инжекция)
-  - [DI Container](#di-container-конструкторный-инжект)
+  - [Provider (@Context)](#provider-context)
+  - [Consumer (@useCtx)](#consumer-usectx)
+  - [Reactive fields](#reactive-fields)
+  - [Optional injection](#optional-injection)
+  - [DI: props vs dependencies](#di-props-vs-dependencies)
+  - [Global services (@inject)](#global-services-inject)
 - [JSX](#jsx)
-  - [Атрибуты](#атрибуты)
-  - [События](#события)
-  - [Стили](#стили)
-  - [CSS-классы](#css-классы)
+  - [Attributes](#attributes)
+  - [Events](#events)
+  - [Styles](#styles)
+  - [CSS classes](#css-classes)
 - [API](#api)
 
 ---
 
-## Установка
+## Installation
 
-### Создание нового проекта (helfy-create)
+### Creating a new project (helfy-create)
 
-Быстрый старт — создать проект одной командой:
+Quick start — create a project with a single command:
 
 ```bash
 npx helfy-create my-app
@@ -52,21 +56,21 @@ cd my-app
 npm run dev
 ```
 
-Без имени (создаст папку `helfy-app`):
+Without a project name (creates `helfy-app`):
 
 ```bash
 npx helfy-create
 ```
 
-Опция `--skip-install` — создать без `npm install` (для оффлайна или своего registry).
+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
 {
@@ -78,11 +82,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 and context scanner before transformation (no pre-scripts in `package.json` needed). The scanners generate `.helfy/di-tokens.ts`, `.helfy/di-registry.ts`, and `.helfy/ctx-tokens.ts`. Add `.helfy` to `.gitignore`.
 
 ### Babel
 
-В `.babelrc` достаточно одного пресета:
+A single preset in `.babelrc` is enough:
 
 ```json
 {
@@ -90,11 +94,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>()`, `@Service<IX>()`, `@UseCase<IX>()`, `@Store`, `@inject<IX>()`, `@useCtx<IX>()`, auto-registration at `createApp`, `@logger()` → `@logger("<ClassName>")` transformation).
 
-### Webpack
+### Webpack / Rspack
 
-Для обработки директив (`@if`, `@for`, `@ref`, `@bind`, `@field`) в `.tsx` файлах подключить loader:
+To process directives (`@if`, `@for`, `@ref`, `@bind`, `@field`) in `.tsx` files, add the loader:
 
 ```javascript
 {
@@ -106,9 +110,11 @@ Babel-плагин автоматически запускает DI-сканер
 }
 ```
 
+The same configuration works with both Webpack and Rspack. Rspack is a faster, Rust-based bundler with webpack-compatible API.
+
 ### TypeScript
 
-В `tsconfig.json` указать:
+In `tsconfig.json` set:
 
 ```json
 {
@@ -121,15 +127,15 @@ Babel-плагин автоматически запускает DI-сканер
 }
 ```
 
-Плагин `@helfy/helfy-ts-plugin` даёт поддержку директив `@if`, `@for`, `@ref`, `@bind`, `@field` в IDE (автодополнение, типизация, переход к определению). Устанавливается отдельно: `npm install @helfy/helfy-ts-plugin`.
+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";
@@ -146,19 +152,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 `@useCtx`, `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";
@@ -186,18 +192,17 @@ class Button {
 }
 ```
 
-Использование:
+Usage:
 
 ```tsx
-<Button label="Нажми" onClick={() => console.log('clicked')} />
+<Button label="Click" onClick={() => console.log('clicked')} />
 ```
 
-При изменении props родителем обновляются только те DOM-узлы, которые читают изменившиеся props.
+When the parent updates props, only the DOM nodes that read the changed props are updated.
 
-### Локальное состояние (@state)
+### Local state (@state)
 
-Декоратор `@state` делает поле реактивным.  
-При изменении значения обновляются только те 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";
@@ -207,7 +212,7 @@ class Counter {
     @state private count = 0;
 
     increment() {
-        this.count++; // обновит только узлы, читающие count
+        this.count++; // updates only nodes that read count
     }
 
     decrement() {
@@ -226,13 +231,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";
@@ -250,9 +255,9 @@ class App {
 }
 ```
 
-### Монтирование в DOM
+### DOM mounting
 
-Типичный bootstrap — через `createApp()`: создаётся экземпляр, вызывается `attach(root)` внутри, хук `onAttached()` срабатывает после вставки в document.
+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";
@@ -262,19 +267,19 @@ createApp({ root: document.getElementById("root")! })
   .mount(App);
 ```
 
-Для сценариев без роутера:
+For scenarios without routing:
 
 ```typescript
 createApp({ root: document.getElementById("root")! }).mount(App);
 ```
 
-Ручное монтирование (без `createApp`): `const app = new App(); app.attach(root)`.
+Manual mounting (without `createApp`): `const app = new App(); app.attach(root)`.
 
-### Привязка к DOM и компонентам (@ref)
+### DOM and component refs (@ref)
 
-Декоратор `@ref` помечает поле для получения ссылки на DOM-элемент или экземпляр компонента. В JSX используется директива `@ref(this.имяПоля)`. Доступ к ссылке возможен после `onMount()`. Для операций вроде `focus()`, требующих элемент в document, используйте `onAttached()`.
+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()`.
 
-**Для компонентов** — родитель получает прокси с доступом только к методам, помеченным `@expose`. Это позволяет явно определить публичный API компонента.
+**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";
@@ -297,7 +302,7 @@ class Form {
     @ref private input!: Input;
 
     onAttached() {
-        this.input.focus();  // доступен только помеченный метод
+        this.input.focus();  // only the exposed method is available
     }
 
     render() {
@@ -306,15 +311,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";
@@ -332,8 +337,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>
         );
@@ -341,24 +346,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;
@@ -369,11 +374,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";
@@ -392,7 +397,7 @@ export class LoginFormContext {
   rememberMe!: FieldState<boolean>;
 
   validateAll(): boolean {
-    // проверка полей, установка field.error
+    // validate fields, set field.error
     return true;
   }
 
@@ -406,9 +411,9 @@ 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
@@ -424,7 +429,7 @@ export class LoginPage {
 }
 ```
 
-**Компонент формы** — инжект через `@useForm`, доступ к полям через `this.form`:
+**Form component** — inject via `@useForm`, access fields via `this.form`:
 
 ```tsx
 import { View, useForm } from "@helfy/helfy";
@@ -443,72 +448,72 @@ export class LoginForm {
         )}
         <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>
+        <label for="remember">Remember me</label>
+        <button type="submit">Sign in</button>
       </form>
     );
   }
 }
 ```
 
-Компоненты-обёртки (TextField, CheckboxField и т.п.) принимают `field` как prop: `<TextField field={this.form.email} label="Email" />` и используют внутри `<input @field(this.props.field) />`.
+Wrapper components (TextField, CheckboxField, etc.) accept `$field` as a writable prop: `<TextField $field={this.form.email} label="Email" />` and use `<input @field(this.props.$field) />` internally. The `$` prefix marks a writable prop — mutable objects like FieldState bypass the default signal-based (readonly) props so form inputs work correctly.
 
-**JSX-директива `@field(expr)`** — одна директива заменяет `@bind` + `onblur` + `class` для ошибок + `aria-invalid`. Компилятор генерирует:
+**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`.
+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>
 }
@@ -516,7 +521,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'];
@@ -532,7 +537,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) {
@@ -542,13 +547,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>
 }
 ```
 
@@ -556,107 +561,214 @@ render() {
 
 ## State Management
 
-### Создание Store
+Helfy uses a three-layer architecture: **@Store** (pure state), **@Service** (infrastructure), **@UseCase** (business logic).
+
+### Dependency flow
+
+```
+@UseCase  ──→  @Store  ←──  @Service
+   │                 ↑
+   └─────────────────┘
+```
+
+- **@Store** — pure reactive state; no dependencies, no side effects. Store does not know about anyone.
+- **@Service** — infrastructure (HTTP, validation, storage); can inject Store and other Services.
+- **@UseCase** — orchestrates business scenarios; injects Store + Services.
+
+### Creating a Store (@Store)
 
-Store -- глобальное реактивное хранилище. Создается классом с декоратором `@Store`, реактивные поля помечаются `@observable`:
+A Store is a global reactive state container. **Requirements:**
+- Empty constructor (no parameters)
+- Only `@state` on fields and `@computed` on getters
+- Mutation methods that only change own state (synchronous; no `await` — async work belongs in @Service)
+- **Forbidden:** `@inject`, `@useCtx`, `@effect`, direct access to HTTP/storage/timers
 
 ```typescript
-import { Store, observable } from "@helfy/helfy";
+import { Store, state, computed } from "@helfy/helfy";
 
 @Store
-class UserStore {
-    @observable name = "Guest";
-    @observable isLoggedIn = false;
-
-    login(name: string) {
-        this.name = name;
-        this.isLoggedIn = true; // подписчики name и isLoggedIn уведомлены
+class TodoStore {
+  @state todos: Todo[] = [];
+  @state filter: "all" | "active" | "completed" = "all";
+
+  @computed get filteredTodos() {
+    switch (this.filter) {
+      case "active": return this.todos.filter(t => !t.completed);
+      case "completed": return this.todos.filter(t => t.completed);
+      default: return this.todos;
     }
+  }
 
-    logout() {
-        this.name = "Guest";
-        this.isLoggedIn = false;
-    }
-}
+  add(title: string) {
+    this.todos = [...this.todos, { id: crypto.randomUUID(), title, completed: false }];
+  }
 
-export default UserStore;
+  toggle(id: string) {
+    this.todos = this.todos.map(t =>
+      t.id === id ? { ...t, completed: !t.completed } : t
+    );
+  }
+
+  setFilter(f: typeof this.filter) {
+    this.filter = f;
+  }
+}
 ```
 
-Декоратор `@Store` добавляет классу:
-- `subscribe(field, callback)` -- подписка на изменение поля, возвращает функцию отписки
-- `unsubscribe(field, callback)` -- отписка
+Fields use `@state` or `@observable` — both create signals.
 
-Декоратор `@observable` превращает поле в реактивное свойство с getter/setter. При записи нового значения все подписчики уведомляются.
+### Infrastructure services (@Service)
 
-### Подписка через @observe
+Use `@Service` for infrastructure: HTTP clients, validators, repositories. **Requirements:**
+- Constructor with DI dependencies (other Services, Store)
+- Provides atomic technical capabilities
+- Can directly mutate Store (e.g. after fetching data)
+- **Forbidden:** `@state`, `@computed`, `@effect` on fields
 
-Декоратор `@observe` связывает поле компонента с полем store. При изменении значения в store компонент автоматически перерендерится:
+```typescript
+import { Service } from "@helfy/helfy";
 
-```tsx
-import { View, observe } from "@helfy/helfy";
-import Stores from "./StoreContext";
-import UserStore from "./UserStore";
+export interface ITodoValidateService {
+  validateTitle(title: string): ValidationResult;
+}
 
-@View
-class Header {
-    @observe(Stores.userStore, 'name')
-    private userName: UserStore['name'];
+@Service<ITodoValidateService>()
+export class TodoValidateService implements ITodoValidateService {
+  validateTitle(title: string) {
+    // ...
+  }
+}
+```
 
-    @observe(Stores.userStore, 'isLoggedIn')
-    private isLoggedIn: UserStore['isLoggedIn'];
+### Business use cases (@UseCase)
 
-    render() {
-        return (
-            <header>
-                @if (this.isLoggedIn) {
-                    <span>Привет, {this.userName}!</span>
-                } @else {
-                    <span>Войдите в систему</span>
-                }
-            </header>
-        );
-    }
+Use `@UseCase` to orchestrate business scenarios. **Requirements:**
+- Constructor with DI (Store, Services)
+- Main public method: `execute`, `perform`, or `handle`
+- Typical flow: validation → call services → update Store → side effects (notifications, analytics)
+- **Forbidden:** `@state`, `@computed`, `@effect` on fields
+
+```typescript
+import { UseCase } from "@helfy/helfy";
+
+@UseCase<ICreateTodoUseCase>()
+export class CreateTodoUseCase implements ICreateTodoUseCase {
+  constructor(
+    private store: TodoStore,
+    private validateService: ITodoValidateService
+  ) {}
+
+  async execute(dto: CreateTodoDto): Promise<Result<Todo, AppError>> {
+    const validation = this.validateService.validateTitle(dto.title);
+    if (!validation.valid) return Err(validation.error);
+
+    const todo = { id: crypto.randomUUID(), ...dto, completed: false };
+    this.store.add(todo);
+    return Ok(todo);
+  }
 }
 ```
 
-Тип поля берется из store через lookup-тип (`UserStore['name']`), что дает полную типобезопасность.
+### HttpClient and ApiClient
+
+Helfy provides an HTTP client and a Query/Mutation layer (similar to TanStack Query) for API data fetching.
 
-### Контекст хранилищ
+**Configure HttpClient** in `createApp`:
+
+```typescript
+createApp({ root: document.getElementById("root")! })
+  .http({
+    baseUrl: "/api",
+    timeout: 10000,
+    headers: { "X-App-Version": "1.0" },
+    queryCacheMaxSize: 100,
+  })
+  .router({ routes })
+  .mount(App);
+```
 
-Рекомендуется создать единый контекст для всех store:
+**Define API interface and implementation** with `@ApiClient` and `@queryConfig`:
 
 ```typescript
-import UserStore from "./UserStore";
-import AppStore from "./AppStore";
+import { ApiClient, queryConfig, QueryBuilder, type Query, type HttpClient } from "@helfy/helfy";
 
-class Stores {
-    static readonly userStore = new UserStore();
-    static readonly appStore = new AppStore();
+export interface TodoApi {
+  todos(): Query<Todo[]>;
 }
 
-export default Stores;
+@ApiClient<TodoApi>()
+export class TodoApiImpl implements TodoApi {
+  constructor(private readonly http: HttpClient) {}
+
+  @queryConfig("todos")
+  todos() {
+    return new QueryBuilder<Todo[]>(["todo"])
+      .fn(() => this.http.get<Todo[]>("/todos"))
+      .staleTime(5 * 60 * 1000)
+      .refetchOnWindowFocus(true);
+  }
+}
+```
+
+**Use `@useQuery` in View** for automatic fetch on mount:
+
+```tsx
+@View
+class TodoList {
+  @useQuery<TodoApi>("todos") private todosQuery!: Query<Todo[]>;
+
+  render() {
+    const q = this.todosQuery;
+    if (q.isLoading) return <Spinner />;
+    if (q.isError) return <ErrorMessage error={q.error} />;
+    return <ul>{q.data?.map((t) => <li>{t.text}</li>)}</ul>;
+  }
+}
+```
+
+**Use `@useMutation`** for imperative mutations:
+
+```tsx
+import type { Mutation } from "@helfy/helfy";
+
+@useMutation<TodoApi>("create") private createTodo!: Mutation<TodoItem, AddTodoDto>;
+
+async handleSubmit() {
+  await this.createTodo.mutateAsync({ title: this.title });
+}
 ```
 
-Использование в компонентах:
+### Accessing Store and UseCase from components
+
+Inject Store and UseCase via `@inject` in View/Context. Prefer UseCase for mutations, Store for reads:
 
 ```tsx
-import Stores from "./StoreContext";
+import { View, inject } from "@helfy/helfy";
 
-// подписка через декоратор
-@observe(Stores.userStore, 'name')
-private userName: string;
+@View
+class TodoList {
+  @inject<ITodoStore>() private store!: ITodoStore;
+  @inject<ICreateTodoUseCase>() private createTodo!: ICreateTodoUseCase;
 
-// прямой вызов метода store
-Stores.userStore.login("Alice");
+  render() {
+    return (
+      <ul>
+        @for (todo of this.store.filteredTodos; track todo.id) {
+          <li>{todo.title}</li>
+        }
+      </ul>
+    );
+  }
+}
 ```
 
 ---
 
-## Логирование (@logger)
+## Logging (@logger)
 
-Декоратор `@logger` инжектирует логгер в классы View, Context, Store и Injectable. Имя класса подставляется на этапе компиляции (Babel-плагин), что сохраняет читаемые имена даже при минификации.
+The `@logger` decorator injects a logger into View, Context, Store, Service, and UseCase 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";
@@ -673,22 +785,23 @@ 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 |
+| Service / Injectable | `TodoValidateService()` | pink |
+| UseCase | `CreateTodoUseCase()` | 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 {
@@ -696,13 +809,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";
@@ -715,36 +828,37 @@ 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 `@useCtx`. Useful for theme, forms, routing, and other shared dependencies.
+
+### Provider (@Context)
 
-### Провайдер (@Context, @provide)
+A class with the `@Context` decorator is a non-rendering provider: it has no `render()` and only renders its children. Use `@state` for reactive fields, `@computed` for derived values; public methods are exposed automatically.
 
-Класс с декоратором `@Context` — не-рендерящий провайдер: он не имеет `render()` и рендерит только своих детей. Поля с `@provide` становятся доступны потребителям ниже по дереву.
+**Constructor:** receives only props from JSX. Define your own props interface (same as View). Use `@inject` for container dependencies.
 
 ```tsx
-import { Context, provide } from "@helfy/helfy";
+import { Context, state } from "@helfy/helfy";
 
 export type TThemeMode = "light" | "dark";
 
 @Context
 export class ThemeContext {
-  @provide({ reactive: true })
+  @state
   mode: TThemeMode = "dark";
 
-  @provide()
   toggle = () => {
     this.mode = this.mode === "dark" ? "light" : "dark";
   };
 }
 ```
 
-Использование в JSX — обёртка вокруг поддерева:
+Usage in JSX — wrap a subtree:
 
 ```tsx
 <ThemeContext>
@@ -753,55 +867,79 @@ export class ThemeContext {
 </ThemeContext>
 ```
 
-Фреймворк рендерит только детей `ThemeContext`; сам провайдер не создаёт DOM-узлов.
+The framework only renders the children of `ThemeContext`; the provider itself does not create DOM nodes.
+
+**Context with typed props** — define an interface and use it in the constructor (same pattern as View):
+
+```tsx
+interface ApiContextProps {
+  baseUrl: string;
+}
+
+@Context
+export class ApiContext {
+  constructor(readonly props: ApiContextProps) {}
+  // ...
+}
+```
 
-### Потребитель (@ctx)
+### Consumer (@useCtx)
 
-Компонент с `@View` может получать значение контекста через `@ctx`:
+A component with `@View` can receive context values via `@useCtx`:
 
 ```tsx
-import { View, ctx } from "@helfy/helfy";
+import { View, useCtx } from "@helfy/helfy";
 import { ThemeContext } from "./ThemeContext";
 
 @View
 class ThemeToggle {
-  @ctx(ThemeContext)
+  @useCtx(ThemeContext)
   private theme!: ThemeContext;
 
   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
 class ModeDisplay {
-  @ctx(ThemeContext, "mode")
+  @useCtx(ThemeContext, "mode")
   private mode!: TThemeMode;
 
   render() {
-    return <span>Текущая тема: {this.mode}</span>;
+    return <span>Current theme: {this.mode}</span>;
   }
 }
 ```
 
-Поиск провайдера идёт вверх по дереву (`_parentView`); используется ближайший провайдер с нужным ключом.
+**Interface-based injection** — for contexts with `@Context<IX>()`, use `@useCtx<ITodoContext>()`:
+
+```tsx
+@useCtx<ITodoContext>()
+private ctx!: ITodoContext;
+
+@useCtx<ITodoContext>("filteredTodos")
+private filteredTodos!: ITodoContext["filteredTodos"];
+```
+
+Provider lookup goes up the tree (`_parentView`); the nearest provider with the matching key is used.
 
-### Реактивные поля
+### Reactive fields
 
-`@provide({ reactive: true })` делает поле реактивным: при изменении все потребители перерендериваются. Для методов достаточно `@provide()` без `reactive`.
+`@state` makes a field reactive: when it changes, all consumers re-render. Public methods are exposed automatically.
 
-**Вычисляемые поля** — геттеры с `@provide({ computed: true, deps: ["field1", "field2"] })` пересчитываются при изменении зависимостей и триггерят перерендер потребителей:
+**Computed fields** — getters with `@computed` recompute when dependencies change and trigger consumer re-renders:
 
 ```tsx
-@provide({ computed: true, deps: ["todos", "filter"] })
+@computed
 get filteredTodos(): Todo[] {
   return this.filter === "active"
     ? this.todos.filter(t => !t.completed)
@@ -809,52 +947,62 @@ get filteredTodos(): Todo[] {
 }
 ```
 
-### Опциональная инжекция
+### Optional injection
 
-Третий аргумент `@ctx` — опции `{ optional?, defaultValue? }`:
+The third argument of `@useCtx` — options `{ optional?, defaultValue? }`:
 
 ```tsx
-@ctx(ThemeContext, { optional: true })
+@useCtx(ThemeContext, { optional: true })
 private theme?: ThemeContext;
 
-@ctx(ThemeContext, "mode", { defaultValue: "light" })
+@useCtx(ThemeContext, "mode", { defaultValue: "light" })
 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: props vs dependencies
 
-### DI Container (конструкторный инжект)
+**View and Context:** constructor receives only props from JSX. Dependencies are injected via field decorators:
+- `@inject<IX>()` — from global container (Store, Service, UseCase)
+- `@useCtx<IX>()` — from tree @Context / @Form providers
 
-Helfy поддерживает DI-контейнер для глобальных сервисов с **compile-time** магией: сервисы помечаются `@Injectable<IX>()`, потребители указывают только тип в конструкторе — без `@inject` и явных токенов.
+**@Service and @UseCase:** constructor DI via `@diParams` (added by Babel plugin) for injected dependencies.
 
-**Конвенция:** последний параметр конструктора — props от родителя; предшествующие параметры резолвятся из контейнера или из @Context по дереву.
+### Global services (@inject)
 
-**Сервис** — обязательно `@Injectable<IX>()` (интерфейс в generic):
+Use `@inject<IX>()` in View/Context to access Store, Service, and UseCase from the container:
 
 ```typescript
+// Define interface and implement with @Service
 export interface ITodoValidateService {
   validate(title: string): ValidationResult;
 }
 
-@Injectable<ITodoValidateService>()
+@Service<ITodoValidateService>()
 export class TodoValidateService implements ITodoValidateService {
   validate(title: string) { ... }
 }
 ```
 
-**Потребитель** — только тип в конструкторе (плагин подставляет токен):
+**Consumer (View)** — inject Store or UseCase:
 
 ```tsx
 @View
 class TodoInput {
-  constructor(
-    private readonly validateService: ITodoValidateService,
-    readonly props: Props
-  ) {}
+  @inject<ITodoValidateService>() private validateService!: ITodoValidateService;
+  @inject<ICreateTodoUseCase>() private createTodo!: ICreateTodoUseCase;
+
+  constructor(readonly props: Props) {}
+
+  render() {
+    // Call UseCase for mutations, Service for validation
+    return <form onsubmit={() => this.createTodo.execute(this.form.getPayload())}>...</form>;
+  }
 }
 ```
 
-**Bootstrap** — регистрация DI подключается автоматически при `createApp` (плагин подставляет `.useDI(registerAllServices)` в цепочку):
+**Bootstrap** — DI registration is automatic at `createApp` (plugin injects `.useDI(registerAllServices)`):
 
 ```typescript
 createApp({ root: document.getElementById("root")! })
@@ -862,9 +1010,9 @@ createApp({ root: document.getElementById("root")! })
   .mount(App);
 ```
 
-Сканер вызывается Babel-плагином перед трансформацией, находит все `@Injectable<IX>()`, генерирует `.helfy/di-tokens.ts` и `.helfy/di-registry.ts`.
+The DI scanner finds `@Store`, `@Service<IX>()`, `@UseCase<IX>()` and generates `.helfy/di-tokens.ts`, `.helfy/di-registry.ts`.
 
-**Fallback** — для ручной настройки доступны `.configureContainer()`, `@inject(token)`, `@Injectable(token)`:
+**Fallback** — for manual setup: `.configureContainer()`, `@Injectable(token)`:
 
 ```typescript
 createApp({ root })
@@ -876,38 +1024,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={{
@@ -916,26 +1064,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>
 ```
@@ -944,33 +1092,39 @@ 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 })` / `@provide({ computed: true, deps })` | Поле | Помечает поле как доступное для `@ctx`. `reactive` — потребители перерендериваются при изменении; `computed` + `deps` — для геттеров |
-| `@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) |
-| `@expose` | Метод | Делает метод доступным родителю при `@ref` на компонент (без `@expose` родитель получает экземпляр целиком) |
-| `@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 |
-
-### Роутинг (SPA)
-
-Helfy включает лёгкий SPA‑роутер. При вызове `createApp().router({ routes }).mount(App)` фреймворк автоматически оборачивает приложение в `RouterContext`, поэтому свой App не нужно оборачивать вручную:
+### 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 | Global reactive state. Empty constructor; only `@state`/`@computed`. No `@inject`, `@useCtx`, `@effect`, or external I/O |
+| `@observable` | Field | Alias for `@state` in Store; makes field reactive |
+| `@Service<IX>()` | Class | Infrastructure (HTTP, validation, repos). Constructor DI. No `@state`/`@computed`. Can mutate Store |
+| `@UseCase<IX>()` | Class | Business scenarios. Injects Store + Service. Main method: `execute`/`perform`/`handle`. No `@state`/`@computed` |
+| `@Context` | Class | Non-rendering context provider; renders only children |
+| `@state` / `@computed` | Context field | In `@Context`: `@state` for reactive fields, `@computed` for derived getters. Public methods exposed automatically |
+| `@inject<IX>()` | Field | Injects Store, Service, or UseCase from container. Use in View/Context |
+| `@useCtx(ContextClass)` / `@useCtx<IX>()` / `@useCtx(ContextClass, field)` | Field | Injects context or a context field from the nearest provider up the tree |
+| `@Injectable<IX>()` | Class | Generic injectable. Prefer `@Service` for infrastructure, `@UseCase` for business logic |
+| `@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)` |
+| `@ApiClient<IX>()` | Class | API client with `@queryConfig` / `@mutationConfig` methods. Registers as Service by interface |
+| `@queryConfig(keyTemplate)` | Method | Marks method as Query; returns QueryBuilder chain, decorator calls `.build()` |
+| `@mutationConfig(options?)` | Method | Marks method as Mutation; merges invalidateQueries, optimisticFn into Mutation |
+| `@useQuery<ApiInterface>(keyOrGetter)` | Field | Injects Query from ApiClient, refetch on mount, reactive data/isLoading/isError |
+| `@useMutation<ApiInterface>(methodName)` | Field | Injects Mutation from ApiClient by method name |
+| `@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:
 
 ```tsx
 // index.ts
@@ -1012,15 +1166,15 @@ class Sidebar {
 
     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";
@@ -1047,7 +1201,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>
     );
@@ -1055,7 +1209,7 @@ class DebugPage {
 }
 ```
 
-**Кастомная страница 404.** Оберните `RouterView` и переопределите слот `notFound`:
+**Custom 404 page.** Wrap `RouterView` and override the `notFound` slot:
 
 ```tsx
 @View
@@ -1070,35 +1224,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
@@ -1106,22 +1260,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
   }
 }
 ```
 
-### Слоты (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";
@@ -1131,24 +1285,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>
                     }
                 }
@@ -1158,15 +1312,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
@@ -1182,20 +1336,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">
@@ -1221,8 +1375,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`.