@treenity/core 1.0.48 → 3.0.1

package/src/mod/docs/13-example.md

@@ -0,0 +1,142 @@
+# 13 — Полный пример: мод от начала до конца
+
+## 1. types.ts — определение компонентов
+
+```ts
+// src/mods/sensor/types.ts
+import { getCtx, registerComp, getComp } from '#comp';
+
+export class SensorConfig {
+  /** @title Интервал @description Секунды между замерами */
+  interval = 5;
+  /** @title Источник */
+  source = '';
+
+  updateInterval(data: { interval: number }) {
+    this.interval = data.interval;
+  }
+
+  async history() {
+    const { node, store } = getCtx();
+    const { items } = await store.getChildren(node.$path, { limit: 100 });
+    return { items: items.map(n => {
+      const r = getComp(n, SensorReading);
+      return r ? { value: r.value, ts: r.ts } : null;
+    }).filter(Boolean) };
+  }
+}
+
+registerComp('sensor.config', SensorConfig);
+
+export class SensorReading {
+  value = 0;
+  ts = 0;
+}
+
+registerComp('sensor.reading', SensorReading);
+```
+
+## 2. service.ts — фоновый процесс
+
+```ts
+// src/mods/sensor/service.ts
+import { register, createNode, type NodeData } from '#core';
+import { getComp } from '#comp';
+import { type ServiceHandle, type ServiceCtx } from '#contexts/service';
+import { SensorConfig } from './types';
+
+register('sensor', 'service', async (node: NodeData, ctx: ServiceCtx) => {
+  const config = getComp(node, SensorConfig);
+  const interval = (config?.interval ?? 5) * 1000;
+
+  const timer = setInterval(async () => {
+    await ctx.store.set(createNode(
+      `${node.$path}/${Date.now()}`,
+      'sensor.reading',
+      { value: Math.random() * 100, ts: Date.now() },
+    ));
+  }, interval);
+
+  return { stop: async () => clearInterval(timer) } satisfies ServiceHandle;
+});
+```
+
+## 3. view.tsx — React-рендер
+
+```tsx
+// src/mods/sensor/view.tsx
+import { register } from '#core';
+import type { View } from '@treenity/react/context';
+import { useChildren } from '@treenity/react/hooks';
+import { SensorConfig, SensorReading } from './types';
+
+// View<T> — типизированный компонент. value: T, ctx: ViewCtx
+const ConfigView: View<SensorConfig> = ({ value }) => {
+  return (
+    <div>
+      <label>Interval: {value.interval}s</label>
+      <label>Source: {value.source}</label>
+    </div>
+  );
+};
+
+const SensorView: View<SensorConfig> = ({ value, ctx }) => {
+  const readings = useChildren(ctx!.node.$path, { limit: 10, watchNew: true });
+
+  return (
+    <div>
+      <h3>Sensor: {ctx!.node.$path}</h3>
+      {readings.map(r => (
+        <div key={r.$path}>
+          {(r as SensorReading).value?.toFixed(1)} @ {new Date((r as SensorReading).ts).toLocaleTimeString()}
+        </div>
+      ))}
+    </div>
+  );
+};
+
+// register принимает Class<T> — типы пробрасываются автоматически
+register(SensorConfig, 'react', ConfigView);
+register(SensorConfig, 'react:list', SensorView);
+```
+
+## 4. schemas.ts — JSON Schema
+
+```ts
+// src/mods/sensor/schemas.ts
+import { register } from '#core';
+
+register('sensor.config', 'schema', () => ({
+  title: 'Sensor Config',
+  properties: {
+    interval: { type: 'number', title: 'Interval (sec)', minimum: 1 },
+    source: { type: 'string', title: 'Source URL' },
+  },
+}));
+```
+
+## 5. Регистрация
+
+```ts
+// src/mods/index.ts — добавить:
+import './sensor/types';
+import './sensor/service';
+
+// src/mods/views.ts — добавить:
+import './sensor/view';
+import './sensor/schemas';
+```
+
+## 6. Seed-данные
+
+```ts
+import { createNode } from '#core';
+
+await store.set(createNode('/sensors/temp', 'sensor', {
+  config: { $type: 'sensor.config', interval: 10, source: 'internal' },
+}));
+
+await store.set(createNode('/sys/autostart/temp-sensor', 'ref', {
+  $ref: '/sensors/temp',
+}));
+```

package/src/mod/docs/14-mod-format.md

@@ -0,0 +1,377 @@
+# Treenity Module Format
+
+Модуль — отдельный npm-пакет, подключаемый к любому инстансу Treenity.
+
+## Структура пакета
+
+```
+treenity-mod-weather/
+  package.json
+  src/
+    index.ts          — defineMod() — точка входа
+    types.ts          — registerComp() — компоненты
+    service.ts        — register(type, 'service', ...) — сервисы
+    view.tsx          — register(type, 'react', ...) — React-рендеры
+    schemas.ts        — register(type, 'schema', ...) — JSON Schema
+```
+
+## package.json
+
+```json
+{
+  "name": "treenity-mod-weather",
+  "version": "1.0.0",
+  "peerDependencies": {
+    "@treenity/core": "^0.1.0"
+  },
+  "treenity": {
+    "name": "weather",
+    "version": "1.0.0",
+    "types": ["weather.sensor", "weather.config", "weather.reading"],
+    "dependencies": ["core-sensors"],
+    "server": "./dist/server.js",
+    "client": "./dist/client.js",
+    "seed": "./dist/seed.js"
+  }
+}
+```
+
+Поле `treenity` — маркер для автоматического обнаружения. Без него пакет игнорируется.
+
+| Поле | Назначение |
+|------|-----------|
+| `name` | Имя модуля (если не указано, берётся из `package.name`) |
+| `version` | Версия модуля (fallback: `package.version`) |
+| `types` | Типы, которые модуль регистрирует (для интроспекции) |
+| `dependencies` | Другие модули, которые нужно загрузить первыми |
+| `server` | Entry point для серверных регистраций |
+| `client` | Entry point для клиентских регистраций (views, schemas) |
+| `seed` | Entry point для seed-данных |
+
+## defineMod() — точка входа
+
+```ts
+// src/index.ts
+import { defineMod } from '@treenity/core';
+
+export default defineMod({
+  name: 'weather',
+  version: '1.0.0',
+  types: ['weather.sensor', 'weather.config'],
+  dependencies: [],
+
+  // Ленивая загрузка серверных регистраций
+  server: () => import('./types').then(() => import('./service')),
+
+  // Ленивая загрузка клиентских регистраций
+  client: () => import('./types').then(() => import('./view')),
+
+  // Seed: создание начальных нод
+  seed: async (store) => {
+    const existing = await store.get('/sensors/weather');
+    if (existing) return; // идемпотентно
+
+    await store.set(createNode('/sensors/weather', 'weather.sensor', {
+      config: { $type: 'weather.config', location: 'Moscow', interval: 60 },
+    }));
+
+    await store.set(createNode('/sys/autostart/weather', 'ref', {
+      $ref: '/sensors/weather',
+    }));
+  },
+
+  onLoad: () => console.log('Weather mod loaded'),
+  onUnload: () => console.log('Weather mod unloaded'),
+});
+```
+
+## Обнаружение
+
+```ts
+import { discoverMods } from '#mod';
+
+// Сканирует node_modules, ищет пакеты с полем "treenity" в package.json
+const manifests = await discoverMods('./node_modules');
+// → [{ name: 'weather', version: '1.0.0', types: [...], server: '...', ... }]
+```
+
+Поддерживает: обычные пакеты, scoped пакеты (`@org/treenity-mod-*`), произвольные имена.
+
+## Загрузка
+
+```ts
+import { discoverMods, loadMods } from '#mod';
+
+const manifests = await discoverMods('./node_modules');
+const result = await loadMods(manifests, 'server', store);
+
+console.log(result.loaded);  // ['core-sensors', 'weather'] — в порядке зависимостей
+console.log(result.failed);  // [{ name: 'broken-mod', error: Error }]
+```
+
+`loadMods()` автоматически:
+1. Сортирует по зависимостям (Kahn's algorithm)
+2. Проверяет что зависимости загружены
+3. Импортирует server/client entry point
+4. Вызывает `onLoad()`
+5. Seed (если target = server и передан store)
+6. Отслеживает состояние в реестре
+
+### Ошибки загрузки
+
+- Неизвестная зависимость → `Error: Mod "X" depends on unknown mod "Y"`
+- Циклическая зависимость → `Error: Circular dependency among mods: A, B, C`
+- Ошибка загрузки → модуль помечается `state: 'failed'`, остальные продолжают грузиться
+
+## Реестр
+
+```ts
+import { getLoadedMods, getMod, isModLoaded } from '#mod';
+
+getLoadedMods();                 // → LoadedMod[]
+getMod('weather');               // → { manifest, mod, state: 'loaded', loadedAt }
+isModLoaded('weather');          // → true
+```
+
+## Dev workflow
+
+Полный рабочий пример — [examples/ticker/](examples/ticker/) — types, service, view, seed, test.
+Скопируй, адаптируй под свой мод.
+
+**Подключение (добавить импорты):**
+```ts
+// src/mods/index.ts
+import './ticker/types';
+import './ticker/service';
+
+// src/mods/views.ts
+import './ticker/view';
+```
+
+**Запуск:**
+```bash
+npm run dev:server    # tsx --watch
+npm run dev:front     # vite HMR
+```
+
+**Дебаг сервера через Chrome DevTools:**
+```bash
+node --inspect -r tsx/esm src/server/index.ts
+# → chrome://inspect
+```
+
+**Тест:**
+```bash
+npx tsx --test src/mods/ticker/ticker.test.ts
+```
+
+**Готово → npm:**
+```bash
+mkdir treenity-mod-ticker && cd treenity-mod-ticker
+npm init
+# Скопировать файлы, заменить @/ на @treenity/core, добавить "treenity" в package.json
+npm publish
+```
+
+---
+
+## Typed Signatures — контракты между модами
+
+Модули связываются через типы. Класс компонента — экспортируемый контракт:
+
+```ts
+// treenity-mod-accounting
+export class Account {
+  static $type = 'accounting.account'
+  balance = 0
+
+  debit(data: { amount: number }) { this.balance -= data.amount }
+}
+```
+
+```ts
+// treenity-mod-billing — зависит от accounting
+import { Account } from 'treenity-mod-accounting'
+
+export class Invoice {
+  static $type = 'billing.invoice'
+
+  async charge(data: { amount: number, account: Account }) {
+    data.account.debit({ amount: data.amount })
+  }
+}
+```
+
+`account: Account` в сигнатуре — это одновременно:
+- **Типизированный параметр** при вызове из кода: `invoice.charge({ amount: 10, account })`
+- **Порт** в визуальном редакторе: входной разъём, к которому подключается Account-нода
+
+Никакого DI-фреймворка, event bus, plugin API. ES import класса = зависимость.
+TypeScript проверяет, JSON Schema генерируется для AI/UI.
+
+---
+
+## Optimistic Updates
+
+Класс компонента — shared kernel между клиентом и сервером. Один код, две среды:
+- **Сервер:** метод выполняется через Immer draft → patches → store.set()
+- **Клиент:** тот же метод выполняется на клоне → мгновенный UI → сервер подтверждает или откатывает
+
+### OptimisticBuffer
+
+```ts
+import { OptimisticBuffer } from '#mod';
+
+const buf = new OptimisticBuffer();
+```
+
+### Цикл: apply → confirm/rollback
+
+```ts
+// 1. Юзер жмёт кнопку — применяем оптимистично
+const { predicted, mutationId } = buf.apply(
+  node,                              // текущая нода
+  'order.status',                    // тип компонента
+  'advance',                         // имя метода
+  (target, data) => target.advance(),// метод
+  undefined,                         // data (аргументы метода)
+);
+// predicted — нода с предсказанным результатом
+// → обновить кэш: cache.put(predicted)
+
+// 2. Отправить экшен на сервер
+trpc.execute.mutate({ path: '/orders/1', type: 'order.status', action: 'advance' });
+
+// 3. Сервер отвечает через подписку (SSE patches)
+const { node: final, rolledBack } = buf.confirm('/orders/1', serverNode);
+// rolledBack = false → предсказание совпало
+// rolledBack = true  → сервер вернул другое, откатили
+
+cache.put(final);
+```
+
+### Множественные мутации
+
+Мутации на одном пути стакаются. При подтверждении первой — остальные ребейзятся:
+
+```ts
+buf.apply(counter0, 'counter', 'increment', incMethod, undefined);  // → count: 1
+buf.apply(counter1, 'counter', 'increment', incMethod, undefined);  // → count: 2
+buf.apply(counter2, 'counter', 'increment', incMethod, undefined);  // → count: 3
+
+buf.getPendingCount('/counters/1');  // → 3
+buf.getOptimistic('/counters/1');    // → { count: 3 }
+
+// Сервер подтверждает первое (count=1)
+buf.confirm('/counters/1', serverNode);  // rebase: оставшиеся 2 переигрываются
+buf.getPendingCount('/counters/1');      // → 2
+```
+
+### Конфликт — сервер всегда прав
+
+```ts
+buf.apply(order, 'order.status', 'advance', advanceMethod, undefined);
+
+const { node, rolledBack } = buf.confirm('/orders/1', cancelledOrder);
+// rolledBack = true, все pending сброшены
+// node = cancelledOrder (серверная версия)
+```
+
+### API
+
+```ts
+buf.hasPending('/path');             // есть ли ожидающие мутации
+buf.getPendingCount('/path');        // сколько
+buf.getPendingCount();               // всего по всем путям
+buf.rollback('/path');               // откатить всё, вернуть baseline
+buf.rollbackById(mutationId);        // откатить конкретную мутацию
+buf.confirmById(mutationId);         // подтвердить конкретную
+buf.expire(30_000);                  // удалить мутации старше 30с
+buf.clear();                         // сбросить всё
+```
+
+### Как работает внутри
+
+1. `apply()` — `structuredClone(node)` → найти компонент → вызвать метод → сохранить baseline + predicted + method + data
+2. `confirm()` — сравнить predicted с serverNode (без $rev) → совпало? drop. нет? rollback all.
+3. `rebase()` — переиграть оставшиеся мутации на новой базе, используя сохранённые method + data
+4. `expire()` — таймаут для зависших мутаций (сервер не ответил)
+
+**Почему хранится method + data:** `structuredClone()` стирает прототипы. Без сохранённой ссылки на метод rebase не может переиграть мутации.
+
+---
+
+## Views — register / Render / RenderContext
+
+Вьюхи НИКОГДА не рендерят дочерние компоненты напрямую. Всё через реестр:
+
+### Регистрация — типобезопасная
+
+```tsx
+import { register } from '@treenity/core/core';
+import type { View } from '@treenity/react/context';
+import { Render, RenderContext } from '@treenity/react/context';
+
+// View<T> — типизированный React-компонент: { value: T, ctx?, onChange? }
+const SensorView: View<WeatherSensor> = ({ value, ctx }) => {
+  const path = ctx!.node.$path;  // путь ноды — через ctx, НЕ из value
+  return <div>{value.location} — {value.temperature}°C</div>;
+};
+
+const SensorRow: View<WeatherSensor> = ({ value, ctx }) => { ... };
+
+// register принимает Class<T> — T пробрасывается в handler автоматически
+register(WeatherSensor, 'react', SensorView);          // detail view
+register(WeatherSensor, 'react:list', SensorRow);      // compact list view
+```
+
+**ЗАПРЕЩЕНО:**
+```tsx
+// WRONG — as any убивает типизацию, прячет ошибки:
+register('weather.sensor', 'react', SensorView as any);
+
+// WRONG — NodeData не смешивать с типами компонентов:
+function SensorRow({ value }: { value: NodeData & WeatherSensor }) { ... }
+
+// WRONG — путь из value (value — данные компонента, не нода):
+const path = value.$path;  // может не существовать!
+```
+
+### Рендер дочерних — ТОЛЬКО через `<Render>`
+
+```tsx
+// WRONG — хардкод, обходит реестр:
+{sensors.map(s => <SensorRow key={s.$path} sensor={s} />)}
+
+// RIGHT — через реестр, композабельно:
+<RenderContext name="react:list">
+  {sensors.map(s => <Render key={s.$path} value={s} />)}
+</RenderContext>
+```
+
+### Контексты
+
+| Контекст | Назначение |
+|----------|-----------|
+| `react` | default/detail view |
+| `react:list` | компактная карточка для списков |
+| `react:edit` | форма редактирования |
+
+Fallback автоматический: `react:list` → `react` → `default`.
+
+### Сигнатура view-функции
+
+```tsx
+// View<T> даёт: value: T, ctx: ViewCtx (node, path, execute), onChange
+const SensorView: View<WeatherSensor> = ({ value, ctx }) => {
+  // value — данные компонента (WeatherSensor fields)
+  // ctx!.node — полная NodeData (с $path, $type, $acl и т.д.)
+  // ctx!.execute(action, data) — вызов экшена
+};
+```
+
+### Почему это важно
+
+- **Композиция:** любой тип рендерит чужих детей, не зная их вьюх
+- **Переопределение:** зарегистрируй новый `react:list` для типа → все списки обновятся
+- **AI visibility:** реестр интроспектируемый, AI находит доступные вьюхи

package/src/mod/docs/15-documenting-types.md

@@ -0,0 +1,156 @@
+# 15 — JSDoc-аннотации для типов
+
+## Как работает
+
+```
+Class JSDoc → extract-schemas.ts → src/schema/generated/*.json → registry('schema') → Inspector / MCP / Client
+```
+
+`registerComp(type, Class)` регистрирует класс. `npm run schema` сканирует AST, извлекает JSDoc, генерирует JSON Schema. Схема загружается при старте через `register(type, 'schema', () => schema)`. Три потребителя:
+
+1. **Inspector** — рендерит формы с лейблами, подсказками, виджетами
+2. **MCP** — `catalog`, `describe_type`, `search_types` для AI-discovery
+3. **TypeCatalog** — программный доступ к каталогу типов из любого контекста
+
+## Справочник тегов
+
+| Тег | Где | Результат | Пример |
+|-----|-----|-----------|--------|
+| _(первая строка)_ | Класс | `schema.title` — название типа | `/** Contact form — receives submissions */` |
+| `@title` | Свойство/метод | `title` — лейбл в форме | `@title Recipient` |
+| `@description` | Свойство/метод | `description` — подсказка | `@description SMTP address` |
+| `@format` | Свойство | UI-виджет (см. таблицу ниже) | `@format image` |
+| `@refType` | Свойство | Ссылка на тип компонента (auto-detect если тип = registered class) | `@refType cafe.mail` |
+| `@pre` | Метод | Поля-предусловия (через пробел) | `@pre source trust` |
+| `@post` | Метод | Поля-результаты (через пробел) | `@post lastSubmission` |
+
+Префикс `_` в имени метода скрывает его из схемы.
+
+## Значения @format
+
+| Format | Виджет | Для чего |
+|--------|--------|----------|
+| `image` | URL + превью | Ссылки на изображения |
+| `textarea` | Многострочное поле | Длинный текст, JSON, описания |
+| `uri` | URL + кликабельная ссылка | Внешние ссылки |
+| `email` | Текстовое поле | Email-адреса |
+| `path` | Поле пути | Treenity node paths (auto при refType) |
+| `tags` | Чипсы с add/remove | Массивы тегов |
+| `tstring` | Мультиязычный редактор | Переводы `{ ru: "...", en: "..." }` |
+| `timestamp` | Форматированная дата | Unix-метки времени |
+
+Без `@format` — рендерится по типу (`string` → input, `number` → number input, `boolean` → checkbox).
+
+## Примеры
+
+### Data-only компонент
+
+**Плохо** — Inspector покажет сырой JSON:
+```typescript
+class BlockHero {
+  title = '';
+  image = '';
+}
+registerComp('mabu.block.hero', BlockHero);
+```
+
+**Хорошо** — Inspector покажет формы с лейблами и виджетами:
+```typescript
+/** Hero banner — full-width section with title, subtitle, CTA */
+class BlockHero {
+  /** @title Title @description Page title */
+  title = '';
+  /** @title Background image @format image */
+  image = '';
+  /** @title Button text @description Learn more */
+  cta = '';
+}
+registerComp('mabu.block.hero', BlockHero);
+```
+
+### Компонент с экшенами
+
+**Плохо** — MCP `catalog` покажет экшен без описания:
+```typescript
+class OrderStatus {
+  value = 'incoming';
+  advance() { /* ... */ }
+}
+```
+
+**Хорошо** — AI видит и понимает экшен:
+```typescript
+/** Kitchen order status — advances through incoming → kitchen → ready */
+class OrderStatus {
+  /** @title Status */
+  value: string = 'incoming';
+  /** @description Advance order to next stage in the flow */
+  advance() { /* ... */ }
+}
+registerComp('order.status', OrderStatus);
+```
+
+### Кросс-ссылки (refType)
+
+```typescript
+/** Contact form — receives submissions, logs them */
+class CafeContact {
+  /** @title Recipient @format email */
+  recipient = '';
+  /** @title Mail service */
+  mailService?: CafeMailService; // auto-detect → refType: "cafe.mail"
+
+  /** @description Submit contact form — validates and logs */
+  submit(data: { name: string; email: string; message: string }) { /* ... */ }
+}
+registerComp('cafe.contact', CafeContact);
+```
+
+### Внешние экшены (register-based)
+
+```typescript
+/** @description Start the Telegram bot polling loop */
+register('brahman.bot', 'action:start', startHandler);
+```
+
+## Чеклист
+
+1. Каждый класс — JSDoc на первой строке: `/** {Noun} — {what it does} */`
+2. Каждое публичное свойство — `@title` (лейбл формы)
+3. `@description` для подсказок (необязательно, но рекомендуется)
+4. `@format` когда нужен специальный виджет
+5. Каждый публичный метод — `@description` (экшен в MCP/Inspector)
+6. `_` prefix для скрытых/внутренних методов
+7. `@refType` auto-detect для свойств с типом registered class
+8. `@pre`/`@post` для документирования зависимостей между полями
+9. После изменений: `npm run schema`
+10. Проверить: `src/schema/generated/{type}.json` — title, properties, methods
+
+## Промпт для LLM
+
+Копируй как system instructions для AI, который создаёт или документирует типы:
+
+```
+## Treenity Type Annotation Rules
+
+When creating or documenting a Treenity component class:
+
+1. CLASS: one-line JSDoc `/** {Noun phrase} — {what it does} */`
+2. PROPERTIES: `/** @title {Label} @description {hint} @format {widget} */`
+   - @title = form label (required for every public field)
+   - @description = placeholder/explanation (recommended)
+   - @format = image | textarea | uri | email | path | tags | tstring | timestamp
+3. METHODS: `/** @description {verb phrase — what the action does} */`
+   - Methods with _ prefix are hidden from schema
+   - Typed args: method(data: { field: type }) auto-generates argument schema
+4. CROSS-REFS: use registered class as property type for auto refType
+   mailService?: CafeMailService → generates refType: "cafe.mail"
+5. EXTERNAL ACTIONS: JSDoc before register() call
+   /** @description Start the bot */ register('bot', 'action:start', handler)
+6. DISCOVERY: use MCP tools to explore existing types:
+   - catalog → list all types with titles
+   - describe_type(name) → full schema + cross-references
+   - search_types(query) → find by keyword
+
+After writing: npm run schema → verify src/schema/generated/{type}.json
+```

package/src/mod/examples/ticker/seed.ts

@@ -0,0 +1,19 @@
+import type { NodeData } from '#core';
+import type { Tree } from '#tree';
+
+export async function seedTicker(store: Tree) {
+  if (await store.get('/demo/ticker')) return;
+
+  await store.set({
+    $path: '/demo/ticker',
+    $type: 'ticker',
+    config: { $type: 'ticker.config', symbol: 'BTC', intervalSec: 5 },
+    mount: { $type: 't.mount.memory' },
+  } as NodeData);
+
+  await store.set({
+    $path: '/sys/autostart/ticker',
+    $type: 'ref',
+    $ref: '/demo/ticker',
+  } as NodeData);
+}