@treenity/core 1.0.47 → 3.0.0

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

@@ -0,0 +1,304 @@
+# 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({
+      $path: '/sensors/weather',
+      $type: 'weather.sensor',
+      config: { $type: 'weather.config', location: 'Moscow', interval: 60 },
+    } as any);
+
+    await store.set({
+      $path: '/sys/autostart/weather',
+      $type: 'ref',
+      $ref: '/sensors/weather',
+    } as any);
+  },
+
+  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 не может переиграть мутации.

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);
+}

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

@@ -0,0 +1,20 @@
+import { getComp } from '#comp';
+import { type NodeData, register } from '#core';
+import { TickerConfig } from './types';
+
+register('ticker', 'service', async (node: NodeData, ctx) => {
+  const config = getComp(node, TickerConfig);
+  const interval = (config?.intervalSec ?? 10) * 1000;
+
+  const timer = setInterval(async () => {
+    const price = 50000 + Math.random() * 1000; // stub — replace with real API
+    await ctx.store.set({
+      $path: `${node.$path}/${Date.now()}`,
+      $type: 'ticker.price',
+      price,
+      ts: Date.now(),
+    } as NodeData);
+  }, interval);
+
+  return { stop: async () => clearInterval(timer) };
+});

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

@@ -0,0 +1,18 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { TickerConfig } from './types';
+
+describe('TickerConfig', () => {
+  it('has sensible defaults', () => {
+    const c = new TickerConfig();
+    assert.equal(c.symbol, 'BTC');
+    assert.equal(c.intervalSec, 10);
+  });
+
+  it('configure updates fields', () => {
+    const c = new TickerConfig();
+    c.configure({ symbol: 'ETH', intervalSec: 30 });
+    assert.equal(c.symbol, 'ETH');
+    assert.equal(c.intervalSec, 30);
+  });
+});

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

@@ -0,0 +1,22 @@
+// Example mod: Ticker — price feed with real-time updates
+import { registerType } from '#comp';
+
+/** Price feed config — trading symbol and polling interval */
+export class TickerConfig {
+  symbol = 'BTC';
+  intervalSec = 10;
+
+  /** @description Update symbol and polling interval */
+  configure(data: { symbol: string; intervalSec: number }) {
+    this.symbol = data.symbol;
+    this.intervalSec = data.intervalSec;
+  }
+}
+registerType('ticker.config', TickerConfig);
+
+/** Latest price snapshot — current price and timestamp */
+export class TickerPrice {
+  price = 0;
+  ts = 0;
+}
+registerType('ticker.price', TickerPrice);

package/src/mod/examples/ticker/view.tsx

@@ -0,0 +1,19 @@
+import { register } from '#core';
+import { useCurrentNode } from '@treenity/react/context';
+import { useChildren } from '@treenity/react/hooks';
+
+register('ticker', 'react', () => {
+  const node = useCurrentNode();
+  const prices = useChildren(node.$path, { limit: 20, watchNew: true });
+
+  return (
+    <div className="space-y-1 p-2">
+      <h3 className="font-bold">{node.$path}</h3>
+      {prices.map(p => (
+        <div key={p.$path} className="text-sm font-mono">
+          ${(p as any).price?.toFixed(2)} — {new Date((p as any).ts).toLocaleTimeString()}
+        </div>
+      ))}
+    </div>
+  );
+});

package/src/mod/index.ts

@@ -0,0 +1,12 @@
+// Treenity Module System — public API
+
+export { defineMod } from './types';
+export type { TreenityMod, ModManifest, ModState, LoadedMod } from './types';
+export { discoverMods } from './discover';
+export { sortByDependencies, loadMods, loadLocalMods, getLoadedMods, getMod, isModLoaded, clearModRegistry } from './loader';
+export type { LoadTarget, LoadResult } from './loader';
+export { OptimisticBuffer } from './optimistic';
+export type { PendingMutation } from './optimistic';
+export { registerPrefab, getPrefab, getModPrefabs, getRegisteredMods, getSeedPrefabs, clearPrefabs } from './prefab';
+export type { PrefabSetup, PrefabMeta, PrefabEntry } from './prefab';
+export { getTypesForMod, inferModFromType, clearTracking } from './tracking';