@foxford/den 2.1.0 → 3.0.0

package/{chunk-TCYGDT2A.js → chunk-E23E2VUC.js}

@@ -6,7 +6,7 @@ function isViewAdapter(value) {
     return false;
   }
   const candidate = value;
-  return typeof candidate.type === "string" && typeof candidate.createIsland === "function" && typeof candidate.installResolver === "function";
+  return typeof candidate.type === "string" && typeof candidate.createIsland === "function" && typeof candidate.renderIsland === "function" && typeof candidate.installResolver === "function";
 }
 function viewAdapterOf(layer) {
   return adapterOfConfig(layer.config);
@@ -14,7 +14,7 @@ function viewAdapterOf(layer) {
 function adapterOfConfig(config) {
   if (!isViewAdapter(config.adapter)) {
     throw new Error(
-      `den/island: view-\u0441\u043B\u043E\u0439 \xAB${config.name}\xBB \u043E\u0431\u044A\u044F\u0432\u043B\u0435\u043D \u0431\u0435\u0437 \u0430\u0434\u0430\u043F\u0442\u0435\u0440\u0430 \u2014 \u043E\u0436\u0438\u0434\u0430\u0435\u0442\u0441\u044F ViewAdapter (type + createIsland + installResolver), \u043D\u0430\u043F\u0440\u0438\u043C\u0435\u0440 reactAdapter()`
+      `den/island: view-\u0441\u043B\u043E\u0439 \xAB${config.name}\xBB \u043E\u0431\u044A\u044F\u0432\u043B\u0435\u043D \u0431\u0435\u0437 \u0430\u0434\u0430\u043F\u0442\u0435\u0440\u0430 \u2014 \u043E\u0436\u0438\u0434\u0430\u0435\u0442\u0441\u044F ViewAdapter (type + createIsland + renderIsland + installResolver), \u043D\u0430\u043F\u0440\u0438\u043C\u0435\u0440 reactAdapter()`
     );
   }
   return config.adapter;

package/{chunk-LJE7K7VD.cjs → chunk-XOJ2VWX4.cjs}

@@ -6,7 +6,7 @@ function isViewAdapter(value) {
     return false;
   }
   const candidate = value;
-  return typeof candidate.type === "string" && typeof candidate.createIsland === "function" && typeof candidate.installResolver === "function";
+  return typeof candidate.type === "string" && typeof candidate.createIsland === "function" && typeof candidate.renderIsland === "function" && typeof candidate.installResolver === "function";
 }
 function viewAdapterOf(layer) {
   return adapterOfConfig(layer.config);
@@ -14,7 +14,7 @@ function viewAdapterOf(layer) {
 function adapterOfConfig(config) {
   if (!isViewAdapter(config.adapter)) {
     throw new Error(
-      `den/island: view-\u0441\u043B\u043E\u0439 \xAB${config.name}\xBB \u043E\u0431\u044A\u044F\u0432\u043B\u0435\u043D \u0431\u0435\u0437 \u0430\u0434\u0430\u043F\u0442\u0435\u0440\u0430 \u2014 \u043E\u0436\u0438\u0434\u0430\u0435\u0442\u0441\u044F ViewAdapter (type + createIsland + installResolver), \u043D\u0430\u043F\u0440\u0438\u043C\u0435\u0440 reactAdapter()`
+      `den/island: view-\u0441\u043B\u043E\u0439 \xAB${config.name}\xBB \u043E\u0431\u044A\u044F\u0432\u043B\u0435\u043D \u0431\u0435\u0437 \u0430\u0434\u0430\u043F\u0442\u0435\u0440\u0430 \u2014 \u043E\u0436\u0438\u0434\u0430\u0435\u0442\u0441\u044F ViewAdapter (type + createIsland + renderIsland + installResolver), \u043D\u0430\u043F\u0440\u0438\u043C\u0435\u0440 reactAdapter()`
     );
   }
   return config.adapter;

package/index.cjs

@@ -16,7 +16,7 @@ var _chunk5DJZZML5cjs = require('./chunk-5DJZZML5.cjs');
 require('./chunk-C7BM4DGX.cjs');
 
 
-var _chunkLJE7K7VDcjs = require('./chunk-LJE7K7VD.cjs');
+var _chunkXOJ2VWX4cjs = require('./chunk-XOJ2VWX4.cjs');
 require('./chunk-A6ZPAM6Z.cjs');
 
 
@@ -717,4 +717,4 @@ function defineLayer(token, options) {
 
 
 
-exports.ActivatableToken = _chunk5DJZZML5cjs.ActivatableToken; exports.ContainerManagerImpl = ContainerManagerImpl; exports.ContainerManagerToken = _chunk5DJZZML5cjs.ContainerManagerToken; exports.GuardRunnerImpl = GuardRunnerImpl; exports.GuardRunnerToken = _chunk5DJZZML5cjs.GuardRunnerToken; exports.NavigationManagerImpl = NavigationManagerImpl; exports.NavigationManagerToken = _chunk5DJZZML5cjs.NavigationManagerToken; exports.RequestContextToken = _chunk5DJZZML5cjs.RequestContextToken; exports.SlotRegistry = _chunk5DJZZML5cjs.SlotRegistry; exports.SlotRegistryToken = _chunk5DJZZML5cjs.SlotRegistryToken; exports.StateCache = StateCache; exports.StateRegistry = StateRegistry; exports.StateRegistryToken = _chunk5DJZZML5cjs.StateRegistryToken; exports.StateSerializerImpl = StateSerializerImpl; exports.StateSerializerToken = _chunk5DJZZML5cjs.StateSerializerToken; exports.ViewLayerToken = _chunkLJE7K7VDcjs.ViewLayerToken; exports.createCore = createCore; exports.defaultGlobalResolver = defaultGlobalResolver; exports.defineActionGuard = defineActionGuard; exports.defineExtension = defineExtension; exports.defineGuard = defineGuard; exports.defineLayer = defineLayer; exports.defineLayout = defineLayout; exports.defineRepository = _chunk5DJZZML5cjs.defineRepository; exports.defineService = _chunk5DJZZML5cjs.defineService; exports.defineSlot = _chunk5DJZZML5cjs.defineSlot; exports.defineViewModel = _chunk5DJZZML5cjs.defineViewModel;
+exports.ActivatableToken = _chunk5DJZZML5cjs.ActivatableToken; exports.ContainerManagerImpl = ContainerManagerImpl; exports.ContainerManagerToken = _chunk5DJZZML5cjs.ContainerManagerToken; exports.GuardRunnerImpl = GuardRunnerImpl; exports.GuardRunnerToken = _chunk5DJZZML5cjs.GuardRunnerToken; exports.NavigationManagerImpl = NavigationManagerImpl; exports.NavigationManagerToken = _chunk5DJZZML5cjs.NavigationManagerToken; exports.RequestContextToken = _chunk5DJZZML5cjs.RequestContextToken; exports.SlotRegistry = _chunk5DJZZML5cjs.SlotRegistry; exports.SlotRegistryToken = _chunk5DJZZML5cjs.SlotRegistryToken; exports.StateCache = StateCache; exports.StateRegistry = StateRegistry; exports.StateRegistryToken = _chunk5DJZZML5cjs.StateRegistryToken; exports.StateSerializerImpl = StateSerializerImpl; exports.StateSerializerToken = _chunk5DJZZML5cjs.StateSerializerToken; exports.ViewLayerToken = _chunkXOJ2VWX4cjs.ViewLayerToken; exports.createCore = createCore; exports.defaultGlobalResolver = defaultGlobalResolver; exports.defineActionGuard = defineActionGuard; exports.defineExtension = defineExtension; exports.defineGuard = defineGuard; exports.defineLayer = defineLayer; exports.defineLayout = defineLayout; exports.defineRepository = _chunk5DJZZML5cjs.defineRepository; exports.defineService = _chunk5DJZZML5cjs.defineService; exports.defineSlot = _chunk5DJZZML5cjs.defineSlot; exports.defineViewModel = _chunk5DJZZML5cjs.defineViewModel;

package/index.d.cts

@@ -4,7 +4,7 @@ import { Container, Token } from '@foxford/ioc';
 import { DefinitionResolver } from './adapter.cjs';
 export { d as defineRepository, a as defineService, b as defineViewModel } from './define-repository-MDEWHqM7.cjs';
 export { D as DefineSlotOptions, S as SlotDefinition, d as defineSlot } from './define-slot-BKvArA02.cjs';
-export { V as ViewAdapter, a as ViewLayerDefinition, b as ViewLayerToken } from './view-adapter-zbHBVVqR.cjs';
+export { V as ViewAdapter, a as ViewLayerDefinition, b as ViewLayerToken } from './view-adapter-BvDC5O4y.cjs';
 
 /**
  * Опции для создания Core Runtime.

package/index.d.ts

@@ -4,7 +4,7 @@ import { Container, Token } from '@foxford/ioc';
 import { DefinitionResolver } from './adapter.js';
 export { d as defineRepository, a as defineService, b as defineViewModel } from './define-repository-Ca62_YCy.js';
 export { D as DefineSlotOptions, S as SlotDefinition, d as defineSlot } from './define-slot-Dil8Kr1A.js';
-export { V as ViewAdapter, a as ViewLayerDefinition, b as ViewLayerToken } from './view-adapter-CSPKr2xy.js';
+export { V as ViewAdapter, a as ViewLayerDefinition, b as ViewLayerToken } from './view-adapter-DtNgyjIf.js';
 
 /**
  * Опции для создания Core Runtime.

package/index.js

@@ -16,7 +16,7 @@ import {
 import "./chunk-WBHHHICS.js";
 import {
   ViewLayerToken
-} from "./chunk-TCYGDT2A.js";
+} from "./chunk-E23E2VUC.js";
 import "./chunk-TPBI6TOU.js";
 import {
   __async

package/island/index.cjs

@@ -2,7 +2,7 @@
 
 
 
-var _chunkLJE7K7VDcjs = require('../chunk-LJE7K7VD.cjs');
+var _chunkXOJ2VWX4cjs = require('../chunk-XOJ2VWX4.cjs');
 
 
 
@@ -10,8 +10,14 @@ var _chunkLJE7K7VDcjs = require('../chunk-LJE7K7VD.cjs');
 var _chunkA6ZPAM6Zcjs = require('../chunk-A6ZPAM6Z.cjs');
 
 
+
 var _chunkXHYR3SGGcjs = require('../chunk-XHYR3SGG.cjs');
 
+// src/island/document.ts
+function isDocumentSource(value) {
+  return typeof value === "object" && value !== null && typeof value.describeDocument === "function";
+}
+
 // src/island/lifecycle.ts
 var _logger = require('@foxford/logger');
 
@@ -28,6 +34,8 @@ function getAppContainer() {
 }
 
 // src/island/lifecycle.ts
+var EMPTY_ROUTE = { params: {}, pathname: "", search: "" };
+var REDIRECT_FOUND = 302;
 function createIslandContainer(descriptor, options = {}) {
   var _a, _b, _c, _d, _e;
   const { parent = getAppContainer() } = options;
@@ -68,13 +76,49 @@ function hydrateIslandState(container, descriptor, denState) {
     }
   }
 }
-function activateIslandViewModels(container, descriptor) {
+function activateIslandViewModels(_0, _1) {
+  return _chunkXHYR3SGGcjs.__async.call(void 0, this, arguments, function* (container, descriptor, route = EMPTY_ROUTE) {
+    var _a;
+    yield Promise.all(
+      ((_a = descriptor.viewModels) != null ? _a : []).map((vm) => _chunkXHYR3SGGcjs.__async.call(void 0, null, null, function* () {
+        var _a2;
+        const instance = container.resolve(vm.token);
+        _chunkA6ZPAM6Zcjs.unitLogger.call(void 0, container, vm.token.description).debug(`\u0430\u043A\u0442\u0438\u0432\u0430\u0446\u0438\u044F VM (${route.pathname || "\u2014"})`);
+        yield (_a2 = instance.activate) == null ? void 0 : _a2.call(instance, route);
+      }))
+    );
+  });
+}
+function collectIslandState(container, descriptor) {
+  var _a, _b;
+  const state = {};
+  for (const vm of (_a = descriptor.viewModels) != null ? _a : []) {
+    const instance = container.resolve(vm.token);
+    if (typeof ((_b = instance.state) == null ? void 0 : _b.get) === "function") {
+      state[vm.token.description] = instance.state.get();
+    }
+  }
+  return state;
+}
+function collectDocumentContribution(container, descriptor) {
   var _a, _b;
+  const contribution = {};
   for (const vm of (_a = descriptor.viewModels) != null ? _a : []) {
     const instance = container.resolve(vm.token);
-    _chunkA6ZPAM6Zcjs.unitLogger.call(void 0, container, vm.token.description).debug("\u0430\u043A\u0442\u0438\u0432\u0430\u0446\u0438\u044F VM (\u0431\u0435\u0437 \u0441\u0435\u0440\u0432\u0435\u0440\u043D\u043E\u0433\u043E denState)");
-    void ((_b = instance.activate) == null ? void 0 : _b.call(instance));
+    if (!isDocumentSource(instance)) {
+      continue;
+    }
+    const part = instance.describeDocument();
+    if (part.head) {
+      contribution.head = _chunkXHYR3SGGcjs.__spreadValues.call(void 0, _chunkXHYR3SGGcjs.__spreadValues.call(void 0, {}, contribution.head), part.head);
+    }
+    const declared = part.status !== void 0 || part.redirect !== void 0;
+    if (declared && contribution.status === void 0) {
+      contribution.status = (_b = part.status) != null ? _b : REDIRECT_FOUND;
+      contribution.redirect = part.redirect;
+    }
   }
+  return contribution;
 }
 function resolveEagerUnits(container, descriptor) {
   var _a;
@@ -89,6 +133,38 @@ function resolveEagerUnits(container, descriptor) {
   }
 }
 
+// src/island/render.ts
+var STATUS_OK = 200;
+function renderApp(descriptor, request) {
+  return _chunkXHYR3SGGcjs.__async.call(void 0, this, null, function* () {
+    var _a, _b;
+    const route = {
+      params: (_a = request.params) != null ? _a : {},
+      pathname: request.pathname,
+      search: (_b = request.search) != null ? _b : ""
+    };
+    const container = createIslandContainer(descriptor, { parent: request.parent });
+    if (container === null) {
+      throw new Error(`den/island: \u043F\u0440\u0438\u043B\u043E\u0436\u0435\u043D\u0438\u0435 \xAB${descriptor.name}\xBB \u043D\u0435 \u0441\u043E\u0431\u0440\u0430\u043B\u043E\u0441\u044C \u2014 \u0440\u0435\u043D\u0434\u0435\u0440 \u043D\u0435\u0432\u043E\u0437\u043C\u043E\u0436\u0435\u043D`);
+    }
+    try {
+      yield activateIslandViewModels(container, descriptor, route);
+      const { head, redirect, status = STATUS_OK } = collectDocumentContribution(container, descriptor);
+      if (status !== STATUS_OK) {
+        return { head, html: "", redirect, state: {}, status };
+      }
+      const state = collectIslandState(container, descriptor);
+      const rendered = _chunkXOJ2VWX4cjs.resolveViewAdapter.call(void 0, container).renderIsland(descriptor, {
+        container,
+        slots: request.slots
+      });
+      return { head, headHtml: rendered.head, html: rendered.html, state, status };
+    } finally {
+      yield container.dispose();
+    }
+  });
+}
+
 // src/island/slot-address.ts
 function slotAddress(app, slot) {
   return `${app}:${slot}`;
@@ -153,4 +229,8 @@ function normalizeRoutes(routes = []) {
 
 
 
-exports.ViewLayerToken = _chunkLJE7K7VDcjs.ViewLayerToken; exports.activateIslandViewModels = activateIslandViewModels; exports.createIslandContainer = createIslandContainer; exports.describeIsland = describeIsland; exports.getAppContainer = getAppContainer; exports.getIslandsSnapshot = getIslandsSnapshot; exports.hydrateIslandState = hydrateIslandState; exports.normalizeRoutes = normalizeRoutes; exports.registerIsland = registerIsland; exports.resolveEagerUnits = resolveEagerUnits; exports.resolveViewAdapter = _chunkLJE7K7VDcjs.resolveViewAdapter; exports.slotAddress = slotAddress; exports.subscribeIslands = subscribeIslands; exports.viewAdapterOf = _chunkLJE7K7VDcjs.viewAdapterOf;
+
+
+
+
+exports.ViewLayerToken = _chunkXOJ2VWX4cjs.ViewLayerToken; exports.activateIslandViewModels = activateIslandViewModels; exports.collectDocumentContribution = collectDocumentContribution; exports.collectIslandState = collectIslandState; exports.createIslandContainer = createIslandContainer; exports.describeIsland = describeIsland; exports.getAppContainer = getAppContainer; exports.getIslandsSnapshot = getIslandsSnapshot; exports.hydrateIslandState = hydrateIslandState; exports.isDocumentSource = isDocumentSource; exports.normalizeRoutes = normalizeRoutes; exports.registerIsland = registerIsland; exports.renderApp = renderApp; exports.resolveEagerUnits = resolveEagerUnits; exports.resolveViewAdapter = _chunkXOJ2VWX4cjs.resolveViewAdapter; exports.slotAddress = slotAddress; exports.subscribeIslands = subscribeIslands; exports.viewAdapterOf = _chunkXOJ2VWX4cjs.viewAdapterOf;

package/island/index.d.cts

@@ -1,9 +1,62 @@
-import { I as IslandDescriptor } from '../view-adapter-zbHBVVqR.cjs';
-export { V as ViewAdapter, a as ViewLayerDefinition, b as ViewLayerToken, r as resolveViewAdapter, v as viewAdapterOf } from '../view-adapter-zbHBVVqR.cjs';
+import { I as IslandDescriptor } from '../view-adapter-BvDC5O4y.cjs';
+export { R as RenderIslandOptions, c as RenderTree, S as ServerRender, d as ServerRenderResult, V as ViewAdapter, a as ViewLayerDefinition, b as ViewLayerToken, r as resolveViewAdapter, v as viewAdapterOf } from '../view-adapter-BvDC5O4y.cjs';
 import { Container } from '@foxford/ioc';
 import { g as GuardDefinition } from '../types-COwVwgzE.cjs';
 import '../define-slot-BKvArA02.cjs';
 
+/** Вклад приложения в `<head>` документа. */
+interface DocumentHead {
+    title?: string;
+    description?: string;
+    keywords?: string;
+    /** При отсутствии хост берёт `title`. */
+    ogTitle?: string;
+    /** При отсутствии хост берёт `description`. */
+    ogDescription?: string;
+}
+/** Что приложение сообщает хосту про страницу, которую оно нарисовало. */
+interface DocumentContribution {
+    head?: DocumentHead;
+    /**
+     * Исход запроса статусом HTTP; не объявлен — `200`.
+     *
+     * Статусом, а не набором признаков вроде «страницы нет»: исход у запроса один, а признаки
+     * позволяют объявить сразу два взаимоисключающих. Тем же статусом исход едет по сети,
+     * поэтому у обоих транспортов дискриминатор общий.
+     *
+     * Нужен отдельно от исключения: `throw` означает, что приложение упало, и хост рисует
+     * плашку вместо него. Приложение, занявшее путь по префиксу (`/legal/*`), обязано уметь
+     * сказать `404` про несуществующий адрес внутри своего пространства.
+     */
+    status?: number;
+    /** Адрес для 3xx. Объявлен без статуса — исход `302`. */
+    redirect?: string;
+}
+/** VM, которой есть что сказать про документ. */
+interface DocumentSource {
+    describeDocument(): DocumentContribution;
+}
+/**
+ * Реализует ли объект {@link DocumentSource}.
+ *
+ * @param value - Проверяемое значение
+ */
+declare function isDocumentSource(value: unknown): value is DocumentSource;
+
+/**
+ * Адрес, по которому рендерится остров.
+ *
+ * Приходит АРГУМЕНТОМ активации, а не через контейнер: контейнер живёт и на клиенте, где
+ * адреса в нём нет, и юнит, потребовавший его через `requires`, упал бы при резолве.
+ */
+interface IslandRoute {
+    /** Путь без search, с ведущим слэшем: `/legal/general`. */
+    pathname: string;
+    /** Строка запроса без `?`; пустая, если её нет. */
+    search: string;
+    /** Параметры, выделенные маршрутом хоста. */
+    params: Record<string, string>;
+}
 /** Опции сборки контейнера острова. */
 interface CreateIslandContainerOptions {
     /**
@@ -42,14 +95,36 @@ declare function createIslandContainer(descriptor: IslandDescriptor, options?: C
  */
 declare function hydrateIslandState(container: Container, descriptor: IslandDescriptor, denState: Record<string, unknown>): void;
 /**
- * Активирует VM острова самостоятельно — когда серверного denState нет (ремоунт острова
- * без данных, чисто клиентский переход). С denState активация не нужна: состояние уже
- * приехало готовым.
+ * Активирует VM острова: каждая считает своё состояние по адресу.
+ *
+ * Параллельно, потому что VM одного острова друг о друге не знают; ждём все — состояние
+ * нужно целиком, а не по частям.
+ *
+ * @param container - Контейнер острова
+ * @param descriptor - Дескриптор острова
+ * @param route - Адрес, по которому рендерится остров
+ */
+declare function activateIslandViewModels(container: Container, descriptor: IslandDescriptor, route?: IslandRoute): Promise<void>;
+/**
+ * Снимает состояние VM острова — операция, обратная {@link hydrateIslandState}.
+ *
+ * @param container - Контейнер острова
+ * @param descriptor - Дескриптор острова
+ * @returns Состояние по ключам `token.description`
+ */
+declare function collectIslandState(container: Container, descriptor: IslandDescriptor): Record<string, unknown>;
+/**
+ * Собирает вклад острова в документ по всем его VM.
+ *
+ * Правила слияния два, и они следуют из смысла полей. `head` — набор полей, поэтому
+ * объявленное позже уточняет объявленное раньше. Исход (`status` вместе с `redirect`) —
+ * ОДНО решение, а не набор: побеждает первое объявленное, и берётся оно целиком, иначе
+ * статус одной VM склеился бы с адресом другой.
  *
  * @param container - Контейнер острова
  * @param descriptor - Дескриптор острова
  */
-declare function activateIslandViewModels(container: Container, descriptor: IslandDescriptor): void;
+declare function collectDocumentContribution(container: Container, descriptor: IslandDescriptor): DocumentContribution;
 /**
  * Поднимает единицы, объявленные `eager`, — те, что обязаны жить с загрузки, а не с первого
  * резолва.
@@ -57,14 +132,59 @@ declare function activateIslandViewModels(container: Container, descriptor: Isla
  * Отдельным шагом, а не внутри сборки контейнера: контейнер строится и на сервере (в vike —
  * прямо в `renderToString`), а сервер живёт один рендер, и поднимать там WS-подписку или
  * прогрев кэша незачем — открытый сокет на каждый рендер это не «eager», это утечка. Зовёт
- * адаптер в точке монтирования, которой на сервере просто нет; серверный прогрев у приложения
- * называется `load`.
+ * адаптер в точке монтирования, которой на сервере просто нет; серверное состояние приложения
+ * считает активация VM.
  *
  * @param container - Контейнер острова
  * @param descriptor - Дескриптор острова
  */
 declare function resolveEagerUnits(container: Container, descriptor: IslandDescriptor): void;
 
+/** Запрос на рендер приложения. */
+interface RenderAppRequest {
+    /** Путь без search, с ведущим слэшем: `/legal/general`. */
+    pathname: string;
+    /** Строка запроса без `?`. */
+    search?: string;
+    /** Параметры, выделенные маршрутом хоста. */
+    params?: Record<string, string>;
+    /**
+     * Родитель контейнера приложения: через него приезжает всё, что настроил исполнитель, —
+     * логгер, конфиг HTTP, выданные возможности. По умолчанию — app-scope контейнер.
+     */
+    parent?: Container;
+    /** Внешние заполнители слотов; для ядра непрозрачны. */
+    slots?: Record<string, unknown>;
+}
+/** Ответ приложения: всё, что хосту нужно, чтобы собрать документ и ответить. */
+interface RenderAppResult {
+    /**
+     * Исход запроса статусом HTTP. `200` — вот страница; всё остальное значит, что страницы
+     * по этому адресу нет, и тело такого ответа выбирает хост: страница ошибки у портала одна
+     * на все приложения.
+     */
+    status: number;
+    /** Разметка приложения; пустая при любом исходе, кроме `200`. */
+    html: string;
+    /** Состояние VM по ключам `token.description` — им гидрируется остров в браузере. */
+    state: Record<string, unknown>;
+    /** Вклад в `<head>` данными. */
+    head?: DocumentHead;
+    /** Вклад в `<head>` готовой разметкой — стили, собранные во время рендера. */
+    headHtml?: string;
+    /** Адрес для 3xx. */
+    redirect?: string;
+}
+/**
+ * Рисует приложение по адресу и отдаёт разметку вместе с состоянием.
+ *
+ * @param descriptor - Дескриптор приложения
+ * @param request - Адрес, родительский контейнер и заполнители слотов
+ * @returns Разметка, состояние и вклад в документ
+ * @throws Если контейнер приложения не собрался — исполнитель решает, чем это показать
+ */
+declare function renderApp(descriptor: IslandDescriptor, request: RenderAppRequest): Promise<RenderAppResult>;
+
 /** Запись живого острова: имя + фактический состав его контейнера. */
 interface IslandRecord {
     /** Уникальный id инстанса острова (островов одного приложения может быть несколько). */
@@ -146,51 +266,4 @@ type AppRoute = string | RouteDeclaration;
  */
 declare function normalizeRoutes(routes?: ReadonlyArray<AppRoute>): RouteDeclaration[];
 
-/** Что приложение отдало серверным рендером. */
-interface ServerRenderResult {
-    /** Разметка дерева — результат переданного рендера. */
-    html: string;
-    /**
-     * Вклад в `<head>` ГОТОВОЙ разметкой: то, что рождается только во время рендера и
-     * данными не описывается.
-     *
-     * Таковы стили CSS-in-JS: стороннее представление у них одно — тег со служебными
-     * атрибутами, по которым клиентский рантайм узнаёт свои правила. Разобрав его на поля,
-     * потеряешь регидратацию, и стили впрыснутся вторым экземпляром. Поэтому вклад в документ
-     * ДАННЫМИ (`DocumentHead` у хостов) остаётся отдельным каналом, а это — разметка.
-     *
-     * Разметка приезжает в документ хоста ДОСЛОВНО, без экранирования — иначе служебные
-     * атрибуты не пережили бы вставку. Отвечает за содержимое приложение: у сетевого
-     * транспорта строка приходит из чужого процесса, и хост её не разбирает.
-     */
-    head?: string;
-}
-/** Рендер дерева в разметку. Его даёт тот, кто серверный рендер исполняет. */
-type RenderTree<Tree = unknown> = (tree: Tree) => string;
-/**
- * Серверный рендер приложения: приложению дают его дерево и рендер, оно возвращает
- * разметку и свой вклад в документ.
- *
- * Рендер приходит АРГУМЕНТОМ, потому что приложение им не владеет: страницу собирает тот,
- * кто держит документ, и приложений на ней может быть несколько. Отдав рендер аргументом,
- * приложение получает обычную функцию — состояние прохода живёт локальной переменной и
- * между запросами не утекает.
- *
- * Подпись одна на оба транспорта, и в этом смысл: у приложения в процессе хоста рендер
- * передаёт хост, у сетевого — его собственный сервер, а `html` и `head` едут ответом.
- * Перевод приложения между транспортами эту часть не задевает.
- *
- * `Tree` — дерево view-фреймворка, для ядра непрозрачное. View-адаптер сужает параметр
- * до своего типа (`ReactServerRender` в `@foxford/den-react`), и приложение пишет проход
- * в терминах СВОЕГО фреймворка.
- *
- * @example
- * serverRender: (tree, render) => {
- *   const sheet = new ServerStyleSheet()
- *
- *   return { head: sheet.getStyleTags(), html: render(sheet.collectStyles(tree)) }
- * }
- */
-type ServerRender<Tree = unknown> = (tree: Tree, render: RenderTree<Tree>) => ServerRenderResult;
-
-export { type AppRoute, type CreateIslandContainerOptions, IslandDescriptor, type IslandRecord, type RenderTree, type RouteDeclaration, type ServerRender, type ServerRenderResult, activateIslandViewModels, createIslandContainer, describeIsland, getAppContainer, getIslandsSnapshot, hydrateIslandState, normalizeRoutes, registerIsland, resolveEagerUnits, slotAddress, subscribeIslands };
+export { type AppRoute, type CreateIslandContainerOptions, type DocumentContribution, type DocumentHead, type DocumentSource, IslandDescriptor, type IslandRecord, type IslandRoute, type RenderAppRequest, type RenderAppResult, type RouteDeclaration, activateIslandViewModels, collectDocumentContribution, collectIslandState, createIslandContainer, describeIsland, getAppContainer, getIslandsSnapshot, hydrateIslandState, isDocumentSource, normalizeRoutes, registerIsland, renderApp, resolveEagerUnits, slotAddress, subscribeIslands };

package/island/index.d.ts

@@ -1,9 +1,62 @@
-import { I as IslandDescriptor } from '../view-adapter-CSPKr2xy.js';
-export { V as ViewAdapter, a as ViewLayerDefinition, b as ViewLayerToken, r as resolveViewAdapter, v as viewAdapterOf } from '../view-adapter-CSPKr2xy.js';
+import { I as IslandDescriptor } from '../view-adapter-DtNgyjIf.js';
+export { R as RenderIslandOptions, c as RenderTree, S as ServerRender, d as ServerRenderResult, V as ViewAdapter, a as ViewLayerDefinition, b as ViewLayerToken, r as resolveViewAdapter, v as viewAdapterOf } from '../view-adapter-DtNgyjIf.js';
 import { Container } from '@foxford/ioc';
 import { g as GuardDefinition } from '../types-COwVwgzE.js';
 import '../define-slot-Dil8Kr1A.js';
 
+/** Вклад приложения в `<head>` документа. */
+interface DocumentHead {
+    title?: string;
+    description?: string;
+    keywords?: string;
+    /** При отсутствии хост берёт `title`. */
+    ogTitle?: string;
+    /** При отсутствии хост берёт `description`. */
+    ogDescription?: string;
+}
+/** Что приложение сообщает хосту про страницу, которую оно нарисовало. */
+interface DocumentContribution {
+    head?: DocumentHead;
+    /**
+     * Исход запроса статусом HTTP; не объявлен — `200`.
+     *
+     * Статусом, а не набором признаков вроде «страницы нет»: исход у запроса один, а признаки
+     * позволяют объявить сразу два взаимоисключающих. Тем же статусом исход едет по сети,
+     * поэтому у обоих транспортов дискриминатор общий.
+     *
+     * Нужен отдельно от исключения: `throw` означает, что приложение упало, и хост рисует
+     * плашку вместо него. Приложение, занявшее путь по префиксу (`/legal/*`), обязано уметь
+     * сказать `404` про несуществующий адрес внутри своего пространства.
+     */
+    status?: number;
+    /** Адрес для 3xx. Объявлен без статуса — исход `302`. */
+    redirect?: string;
+}
+/** VM, которой есть что сказать про документ. */
+interface DocumentSource {
+    describeDocument(): DocumentContribution;
+}
+/**
+ * Реализует ли объект {@link DocumentSource}.
+ *
+ * @param value - Проверяемое значение
+ */
+declare function isDocumentSource(value: unknown): value is DocumentSource;
+
+/**
+ * Адрес, по которому рендерится остров.
+ *
+ * Приходит АРГУМЕНТОМ активации, а не через контейнер: контейнер живёт и на клиенте, где
+ * адреса в нём нет, и юнит, потребовавший его через `requires`, упал бы при резолве.
+ */
+interface IslandRoute {
+    /** Путь без search, с ведущим слэшем: `/legal/general`. */
+    pathname: string;
+    /** Строка запроса без `?`; пустая, если её нет. */
+    search: string;
+    /** Параметры, выделенные маршрутом хоста. */
+    params: Record<string, string>;
+}
 /** Опции сборки контейнера острова. */
 interface CreateIslandContainerOptions {
     /**
@@ -42,14 +95,36 @@ declare function createIslandContainer(descriptor: IslandDescriptor, options?: C
  */
 declare function hydrateIslandState(container: Container, descriptor: IslandDescriptor, denState: Record<string, unknown>): void;
 /**
- * Активирует VM острова самостоятельно — когда серверного denState нет (ремоунт острова
- * без данных, чисто клиентский переход). С denState активация не нужна: состояние уже
- * приехало готовым.
+ * Активирует VM острова: каждая считает своё состояние по адресу.
+ *
+ * Параллельно, потому что VM одного острова друг о друге не знают; ждём все — состояние
+ * нужно целиком, а не по частям.
+ *
+ * @param container - Контейнер острова
+ * @param descriptor - Дескриптор острова
+ * @param route - Адрес, по которому рендерится остров
+ */
+declare function activateIslandViewModels(container: Container, descriptor: IslandDescriptor, route?: IslandRoute): Promise<void>;
+/**
+ * Снимает состояние VM острова — операция, обратная {@link hydrateIslandState}.
+ *
+ * @param container - Контейнер острова
+ * @param descriptor - Дескриптор острова
+ * @returns Состояние по ключам `token.description`
+ */
+declare function collectIslandState(container: Container, descriptor: IslandDescriptor): Record<string, unknown>;
+/**
+ * Собирает вклад острова в документ по всем его VM.
+ *
+ * Правила слияния два, и они следуют из смысла полей. `head` — набор полей, поэтому
+ * объявленное позже уточняет объявленное раньше. Исход (`status` вместе с `redirect`) —
+ * ОДНО решение, а не набор: побеждает первое объявленное, и берётся оно целиком, иначе
+ * статус одной VM склеился бы с адресом другой.
  *
  * @param container - Контейнер острова
  * @param descriptor - Дескриптор острова
  */
-declare function activateIslandViewModels(container: Container, descriptor: IslandDescriptor): void;
+declare function collectDocumentContribution(container: Container, descriptor: IslandDescriptor): DocumentContribution;
 /**
  * Поднимает единицы, объявленные `eager`, — те, что обязаны жить с загрузки, а не с первого
  * резолва.
@@ -57,14 +132,59 @@ declare function activateIslandViewModels(container: Container, descriptor: Isla
  * Отдельным шагом, а не внутри сборки контейнера: контейнер строится и на сервере (в vike —
  * прямо в `renderToString`), а сервер живёт один рендер, и поднимать там WS-подписку или
  * прогрев кэша незачем — открытый сокет на каждый рендер это не «eager», это утечка. Зовёт
- * адаптер в точке монтирования, которой на сервере просто нет; серверный прогрев у приложения
- * называется `load`.
+ * адаптер в точке монтирования, которой на сервере просто нет; серверное состояние приложения
+ * считает активация VM.
  *
  * @param container - Контейнер острова
  * @param descriptor - Дескриптор острова
  */
 declare function resolveEagerUnits(container: Container, descriptor: IslandDescriptor): void;
 
+/** Запрос на рендер приложения. */
+interface RenderAppRequest {
+    /** Путь без search, с ведущим слэшем: `/legal/general`. */
+    pathname: string;
+    /** Строка запроса без `?`. */
+    search?: string;
+    /** Параметры, выделенные маршрутом хоста. */
+    params?: Record<string, string>;
+    /**
+     * Родитель контейнера приложения: через него приезжает всё, что настроил исполнитель, —
+     * логгер, конфиг HTTP, выданные возможности. По умолчанию — app-scope контейнер.
+     */
+    parent?: Container;
+    /** Внешние заполнители слотов; для ядра непрозрачны. */
+    slots?: Record<string, unknown>;
+}
+/** Ответ приложения: всё, что хосту нужно, чтобы собрать документ и ответить. */
+interface RenderAppResult {
+    /**
+     * Исход запроса статусом HTTP. `200` — вот страница; всё остальное значит, что страницы
+     * по этому адресу нет, и тело такого ответа выбирает хост: страница ошибки у портала одна
+     * на все приложения.
+     */
+    status: number;
+    /** Разметка приложения; пустая при любом исходе, кроме `200`. */
+    html: string;
+    /** Состояние VM по ключам `token.description` — им гидрируется остров в браузере. */
+    state: Record<string, unknown>;
+    /** Вклад в `<head>` данными. */
+    head?: DocumentHead;
+    /** Вклад в `<head>` готовой разметкой — стили, собранные во время рендера. */
+    headHtml?: string;
+    /** Адрес для 3xx. */
+    redirect?: string;
+}
+/**
+ * Рисует приложение по адресу и отдаёт разметку вместе с состоянием.
+ *
+ * @param descriptor - Дескриптор приложения
+ * @param request - Адрес, родительский контейнер и заполнители слотов
+ * @returns Разметка, состояние и вклад в документ
+ * @throws Если контейнер приложения не собрался — исполнитель решает, чем это показать
+ */
+declare function renderApp(descriptor: IslandDescriptor, request: RenderAppRequest): Promise<RenderAppResult>;
+
 /** Запись живого острова: имя + фактический состав его контейнера. */
 interface IslandRecord {
     /** Уникальный id инстанса острова (островов одного приложения может быть несколько). */
@@ -146,51 +266,4 @@ type AppRoute = string | RouteDeclaration;
  */
 declare function normalizeRoutes(routes?: ReadonlyArray<AppRoute>): RouteDeclaration[];
 
-/** Что приложение отдало серверным рендером. */
-interface ServerRenderResult {
-    /** Разметка дерева — результат переданного рендера. */
-    html: string;
-    /**
-     * Вклад в `<head>` ГОТОВОЙ разметкой: то, что рождается только во время рендера и
-     * данными не описывается.
-     *
-     * Таковы стили CSS-in-JS: стороннее представление у них одно — тег со служебными
-     * атрибутами, по которым клиентский рантайм узнаёт свои правила. Разобрав его на поля,
-     * потеряешь регидратацию, и стили впрыснутся вторым экземпляром. Поэтому вклад в документ
-     * ДАННЫМИ (`DocumentHead` у хостов) остаётся отдельным каналом, а это — разметка.
-     *
-     * Разметка приезжает в документ хоста ДОСЛОВНО, без экранирования — иначе служебные
-     * атрибуты не пережили бы вставку. Отвечает за содержимое приложение: у сетевого
-     * транспорта строка приходит из чужого процесса, и хост её не разбирает.
-     */
-    head?: string;
-}
-/** Рендер дерева в разметку. Его даёт тот, кто серверный рендер исполняет. */
-type RenderTree<Tree = unknown> = (tree: Tree) => string;
-/**
- * Серверный рендер приложения: приложению дают его дерево и рендер, оно возвращает
- * разметку и свой вклад в документ.
- *
- * Рендер приходит АРГУМЕНТОМ, потому что приложение им не владеет: страницу собирает тот,
- * кто держит документ, и приложений на ней может быть несколько. Отдав рендер аргументом,
- * приложение получает обычную функцию — состояние прохода живёт локальной переменной и
- * между запросами не утекает.
- *
- * Подпись одна на оба транспорта, и в этом смысл: у приложения в процессе хоста рендер
- * передаёт хост, у сетевого — его собственный сервер, а `html` и `head` едут ответом.
- * Перевод приложения между транспортами эту часть не задевает.
- *
- * `Tree` — дерево view-фреймворка, для ядра непрозрачное. View-адаптер сужает параметр
- * до своего типа (`ReactServerRender` в `@foxford/den-react`), и приложение пишет проход
- * в терминах СВОЕГО фреймворка.
- *
- * @example
- * serverRender: (tree, render) => {
- *   const sheet = new ServerStyleSheet()
- *
- *   return { head: sheet.getStyleTags(), html: render(sheet.collectStyles(tree)) }
- * }
- */
-type ServerRender<Tree = unknown> = (tree: Tree, render: RenderTree<Tree>) => ServerRenderResult;
-
-export { type AppRoute, type CreateIslandContainerOptions, IslandDescriptor, type IslandRecord, type RenderTree, type RouteDeclaration, type ServerRender, type ServerRenderResult, activateIslandViewModels, createIslandContainer, describeIsland, getAppContainer, getIslandsSnapshot, hydrateIslandState, normalizeRoutes, registerIsland, resolveEagerUnits, slotAddress, subscribeIslands };
+export { type AppRoute, type CreateIslandContainerOptions, type DocumentContribution, type DocumentHead, type DocumentSource, IslandDescriptor, type IslandRecord, type IslandRoute, type RenderAppRequest, type RenderAppResult, type RouteDeclaration, activateIslandViewModels, collectDocumentContribution, collectIslandState, createIslandContainer, describeIsland, getAppContainer, getIslandsSnapshot, hydrateIslandState, isDocumentSource, normalizeRoutes, registerIsland, renderApp, resolveEagerUnits, slotAddress, subscribeIslands };

package/island/index.js

@@ -2,16 +2,22 @@ import {
   ViewLayerToken,
   resolveViewAdapter,
   viewAdapterOf
-} from "../chunk-TCYGDT2A.js";
+} from "../chunk-E23E2VUC.js";
 import {
   LoggerToken,
   logger,
   unitLogger
 } from "../chunk-TPBI6TOU.js";
 import {
+  __async,
   __spreadValues
 } from "../chunk-HJO26HIQ.js";
 
+// src/island/document.ts
+function isDocumentSource(value) {
+  return typeof value === "object" && value !== null && typeof value.describeDocument === "function";
+}
+
 // src/island/lifecycle.ts
 import { log } from "@foxford/logger";
 
@@ -28,6 +34,8 @@ function getAppContainer() {
 }
 
 // src/island/lifecycle.ts
+var EMPTY_ROUTE = { params: {}, pathname: "", search: "" };
+var REDIRECT_FOUND = 302;
 function createIslandContainer(descriptor, options = {}) {
   var _a, _b, _c, _d, _e;
   const { parent = getAppContainer() } = options;
@@ -68,13 +76,49 @@ function hydrateIslandState(container, descriptor, denState) {
     }
   }
 }
-function activateIslandViewModels(container, descriptor) {
+function activateIslandViewModels(_0, _1) {
+  return __async(this, arguments, function* (container, descriptor, route = EMPTY_ROUTE) {
+    var _a;
+    yield Promise.all(
+      ((_a = descriptor.viewModels) != null ? _a : []).map((vm) => __async(null, null, function* () {
+        var _a2;
+        const instance = container.resolve(vm.token);
+        unitLogger(container, vm.token.description).debug(`\u0430\u043A\u0442\u0438\u0432\u0430\u0446\u0438\u044F VM (${route.pathname || "\u2014"})`);
+        yield (_a2 = instance.activate) == null ? void 0 : _a2.call(instance, route);
+      }))
+    );
+  });
+}
+function collectIslandState(container, descriptor) {
   var _a, _b;
+  const state = {};
   for (const vm of (_a = descriptor.viewModels) != null ? _a : []) {
     const instance = container.resolve(vm.token);
-    unitLogger(container, vm.token.description).debug("\u0430\u043A\u0442\u0438\u0432\u0430\u0446\u0438\u044F VM (\u0431\u0435\u0437 \u0441\u0435\u0440\u0432\u0435\u0440\u043D\u043E\u0433\u043E denState)");
-    void ((_b = instance.activate) == null ? void 0 : _b.call(instance));
+    if (typeof ((_b = instance.state) == null ? void 0 : _b.get) === "function") {
+      state[vm.token.description] = instance.state.get();
+    }
   }
+  return state;
+}
+function collectDocumentContribution(container, descriptor) {
+  var _a, _b;
+  const contribution = {};
+  for (const vm of (_a = descriptor.viewModels) != null ? _a : []) {
+    const instance = container.resolve(vm.token);
+    if (!isDocumentSource(instance)) {
+      continue;
+    }
+    const part = instance.describeDocument();
+    if (part.head) {
+      contribution.head = __spreadValues(__spreadValues({}, contribution.head), part.head);
+    }
+    const declared = part.status !== void 0 || part.redirect !== void 0;
+    if (declared && contribution.status === void 0) {
+      contribution.status = (_b = part.status) != null ? _b : REDIRECT_FOUND;
+      contribution.redirect = part.redirect;
+    }
+  }
+  return contribution;
 }
 function resolveEagerUnits(container, descriptor) {
   var _a;
@@ -89,6 +133,38 @@ function resolveEagerUnits(container, descriptor) {
   }
 }
 
+// src/island/render.ts
+var STATUS_OK = 200;
+function renderApp(descriptor, request) {
+  return __async(this, null, function* () {
+    var _a, _b;
+    const route = {
+      params: (_a = request.params) != null ? _a : {},
+      pathname: request.pathname,
+      search: (_b = request.search) != null ? _b : ""
+    };
+    const container = createIslandContainer(descriptor, { parent: request.parent });
+    if (container === null) {
+      throw new Error(`den/island: \u043F\u0440\u0438\u043B\u043E\u0436\u0435\u043D\u0438\u0435 \xAB${descriptor.name}\xBB \u043D\u0435 \u0441\u043E\u0431\u0440\u0430\u043B\u043E\u0441\u044C \u2014 \u0440\u0435\u043D\u0434\u0435\u0440 \u043D\u0435\u0432\u043E\u0437\u043C\u043E\u0436\u0435\u043D`);
+    }
+    try {
+      yield activateIslandViewModels(container, descriptor, route);
+      const { head, redirect, status = STATUS_OK } = collectDocumentContribution(container, descriptor);
+      if (status !== STATUS_OK) {
+        return { head, html: "", redirect, state: {}, status };
+      }
+      const state = collectIslandState(container, descriptor);
+      const rendered = resolveViewAdapter(container).renderIsland(descriptor, {
+        container,
+        slots: request.slots
+      });
+      return { head, headHtml: rendered.head, html: rendered.html, state, status };
+    } finally {
+      yield container.dispose();
+    }
+  });
+}
+
 // src/island/slot-address.ts
 function slotAddress(app, slot) {
   return `${app}:${slot}`;
@@ -141,13 +217,17 @@ function normalizeRoutes(routes = []) {
 export {
   ViewLayerToken,
   activateIslandViewModels,
+  collectDocumentContribution,
+  collectIslandState,
   createIslandContainer,
   describeIsland,
   getAppContainer,
   getIslandsSnapshot,
   hydrateIslandState,
+  isDocumentSource,
   normalizeRoutes,
   registerIsland,
+  renderApp,
   resolveEagerUnits,
   resolveViewAdapter,
   slotAddress,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxford/den",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "Den — декларативный метафреймворк Foxford (core runtime)",
   "keywords": [
     "foxford",
@@ -56,13 +56,13 @@
     "chunk-5DJZZML5.cjs",
     "chunk-A6ZPAM6Z.cjs",
     "chunk-C7BM4DGX.cjs",
+    "chunk-E23E2VUC.js",
     "chunk-HJO26HIQ.js",
-    "chunk-LJE7K7VD.cjs",
-    "chunk-TCYGDT2A.js",
     "chunk-TPBI6TOU.js",
     "chunk-WBHHHICS.js",
     "chunk-WRQC6BVJ.js",
     "chunk-XHYR3SGG.cjs",
+    "chunk-XOJ2VWX4.cjs",
     "define-repository-Ca62_YCy.d.ts",
     "define-repository-MDEWHqM7.d.cts",
     "define-slot-BKvArA02.d.cts",
@@ -79,9 +79,9 @@
     "package.json",
     "types-COwVwgzE.d.cts",
     "types-COwVwgzE.d.ts",
-    "view-adapter-CSPKr2xy.d.ts",
-    "view-adapter-zbHBVVqR.d.cts"
+    "view-adapter-BvDC5O4y.d.cts",
+    "view-adapter-DtNgyjIf.d.ts"
   ],
-  "sha": "d6b3073",
+  "sha": "ba6123d",
   "scripts": {}
 }

package/{view-adapter-zbHBVVqR.d.cts → view-adapter-BvDC5O4y.d.cts}

@@ -54,7 +54,7 @@ interface IslandDescriptor {
      *
      * Поднимаются при МОНТИРОВАНИИ острова, а не при сборке контейнера: контейнер строится и на
      * сервере, а сервер живёт один рендер — открытая там WS-подписка это не «eager», а утечка.
-     * Серверный прогрев у приложения называется `load`.
+     * Серверное состояние приложения считает активация VM.
      */
     eager?: ReadonlyArray<Token<unknown>>;
     /**
@@ -67,6 +67,60 @@ interface IslandDescriptor {
     slots?: Readonly<Record<string, SlotDefinition>>;
 }
 
+/** Что приложение отдало серверным рендером. */
+interface ServerRenderResult {
+    /** Разметка дерева — результат переданного рендера. */
+    html: string;
+    /**
+     * Вклад в `<head>` ГОТОВОЙ разметкой: то, что рождается только во время рендера и
+     * данными не описывается.
+     *
+     * Таковы стили CSS-in-JS: стороннее представление у них одно — тег со служебными
+     * атрибутами, по которым клиентский рантайм узнаёт свои правила. Разобрав его на поля,
+     * потеряешь регидратацию, и стили впрыснутся вторым экземпляром. Поэтому вклад в документ
+     * ДАННЫМИ (`DocumentHead` у хостов) остаётся отдельным каналом, а это — разметка.
+     *
+     * Разметка приезжает в документ хоста ДОСЛОВНО, без экранирования — иначе служебные
+     * атрибуты не пережили бы вставку. Отвечает за содержимое приложение: у сетевого
+     * транспорта строка приходит из чужого процесса, и хост её не разбирает.
+     */
+    head?: string;
+}
+/** Рендер дерева в разметку. Его даёт тот, кто серверный рендер исполняет. */
+type RenderTree<Tree = unknown> = (tree: Tree) => string;
+/**
+ * Серверный рендер приложения: приложению дают его дерево и рендер, оно возвращает
+ * разметку и свой вклад в документ.
+ *
+ * Рендер приходит АРГУМЕНТОМ, потому что приложение им не владеет: страницу собирает тот,
+ * кто держит документ, и приложений на ней может быть несколько. Отдав рендер аргументом,
+ * приложение получает обычную функцию — состояние прохода живёт локальной переменной и
+ * между запросами не утекает.
+ *
+ * Подпись одна на оба транспорта, и в этом смысл: у приложения в процессе хоста рендер
+ * передаёт хост, у сетевого — его собственный сервер, а `html` и `head` едут ответом.
+ * Перевод приложения между транспортами эту часть не задевает.
+ *
+ * `Tree` — дерево view-фреймворка, для ядра непрозрачное. View-адаптер сужает параметр
+ * до своего типа (`ReactServerRender` в `@foxford/den-react`), и приложение пишет проход
+ * в терминах СВОЕГО фреймворка.
+ *
+ * @example
+ * serverRender: (tree, render) => {
+ *   const sheet = new ServerStyleSheet()
+ *
+ *   return { head: sheet.getStyleTags(), html: render(sheet.collectStyles(tree)) }
+ * }
+ */
+type ServerRender<Tree = unknown> = (tree: Tree, render: RenderTree<Tree>) => ServerRenderResult;
+
+/** Что нужно адаптеру, чтобы отрисовать остров на сервере. */
+interface RenderIslandOptions {
+    /** Контейнер острова — уже собранный, с активированными VM. */
+    container: Container;
+    /** Внешние заполнители слотов; для ядра непрозрачны, как и само дерево. */
+    slots?: Record<string, unknown>;
+}
 /**
  * Порт view-адаптера. Реализуется пакетом фреймворка (`@foxford/den-react` и его аналоги),
  * объявляется приложением через `defineLayer(ViewLayerToken, { adapter })`.
@@ -82,6 +136,18 @@ interface ViewAdapter {
      * @returns Компонент фреймворка — для ядра непрозрачен
      */
     createIsland(descriptor: IslandDescriptor): unknown;
+    /**
+     * Отрисовывает остров в разметку на сервере.
+     *
+     * Единственная операция острова, которую ядро не может сделать само: `renderToString` —
+     * функция конкретного фреймворка, а ядро view-агностично. Здесь же адаптер исполняет
+     * `serverRender` приложения, если тот объявлен, — тип дерева известен только адаптеру.
+     *
+     * @param descriptor - Дескриптор острова
+     * @param options - Контейнер острова и заполнители слотов
+     * @returns Разметка и вклад в `<head>` готовой разметкой
+     */
+    renderIsland(descriptor: IslandDescriptor, options: RenderIslandOptions): ServerRenderResult;
     /**
      * Ставит стратегию резолва `define*` во view (`installResolver` из `@foxford/den/adapter`).
      * У каждого фреймворка она своя: у React — хук поверх контекста контейнера, у Vue —
@@ -119,4 +185,4 @@ declare function viewAdapterOf(layer: ViewLayerDefinition): ViewAdapter;
  */
 declare function resolveViewAdapter(container: Container): ViewAdapter;
 
-export { type IslandDescriptor as I, type ViewAdapter as V, type ViewLayerDefinition as a, ViewLayerToken as b, resolveViewAdapter as r, viewAdapterOf as v };
+export { type IslandDescriptor as I, type RenderIslandOptions as R, type ServerRender as S, type ViewAdapter as V, type ViewLayerDefinition as a, ViewLayerToken as b, type RenderTree as c, type ServerRenderResult as d, resolveViewAdapter as r, viewAdapterOf as v };

package/{view-adapter-CSPKr2xy.d.ts → view-adapter-DtNgyjIf.d.ts}

@@ -54,7 +54,7 @@ interface IslandDescriptor {
      *
      * Поднимаются при МОНТИРОВАНИИ острова, а не при сборке контейнера: контейнер строится и на
      * сервере, а сервер живёт один рендер — открытая там WS-подписка это не «eager», а утечка.
-     * Серверный прогрев у приложения называется `load`.
+     * Серверное состояние приложения считает активация VM.
      */
     eager?: ReadonlyArray<Token<unknown>>;
     /**
@@ -67,6 +67,60 @@ interface IslandDescriptor {
     slots?: Readonly<Record<string, SlotDefinition>>;
 }
 
+/** Что приложение отдало серверным рендером. */
+interface ServerRenderResult {
+    /** Разметка дерева — результат переданного рендера. */
+    html: string;
+    /**
+     * Вклад в `<head>` ГОТОВОЙ разметкой: то, что рождается только во время рендера и
+     * данными не описывается.
+     *
+     * Таковы стили CSS-in-JS: стороннее представление у них одно — тег со служебными
+     * атрибутами, по которым клиентский рантайм узнаёт свои правила. Разобрав его на поля,
+     * потеряешь регидратацию, и стили впрыснутся вторым экземпляром. Поэтому вклад в документ
+     * ДАННЫМИ (`DocumentHead` у хостов) остаётся отдельным каналом, а это — разметка.
+     *
+     * Разметка приезжает в документ хоста ДОСЛОВНО, без экранирования — иначе служебные
+     * атрибуты не пережили бы вставку. Отвечает за содержимое приложение: у сетевого
+     * транспорта строка приходит из чужого процесса, и хост её не разбирает.
+     */
+    head?: string;
+}
+/** Рендер дерева в разметку. Его даёт тот, кто серверный рендер исполняет. */
+type RenderTree<Tree = unknown> = (tree: Tree) => string;
+/**
+ * Серверный рендер приложения: приложению дают его дерево и рендер, оно возвращает
+ * разметку и свой вклад в документ.
+ *
+ * Рендер приходит АРГУМЕНТОМ, потому что приложение им не владеет: страницу собирает тот,
+ * кто держит документ, и приложений на ней может быть несколько. Отдав рендер аргументом,
+ * приложение получает обычную функцию — состояние прохода живёт локальной переменной и
+ * между запросами не утекает.
+ *
+ * Подпись одна на оба транспорта, и в этом смысл: у приложения в процессе хоста рендер
+ * передаёт хост, у сетевого — его собственный сервер, а `html` и `head` едут ответом.
+ * Перевод приложения между транспортами эту часть не задевает.
+ *
+ * `Tree` — дерево view-фреймворка, для ядра непрозрачное. View-адаптер сужает параметр
+ * до своего типа (`ReactServerRender` в `@foxford/den-react`), и приложение пишет проход
+ * в терминах СВОЕГО фреймворка.
+ *
+ * @example
+ * serverRender: (tree, render) => {
+ *   const sheet = new ServerStyleSheet()
+ *
+ *   return { head: sheet.getStyleTags(), html: render(sheet.collectStyles(tree)) }
+ * }
+ */
+type ServerRender<Tree = unknown> = (tree: Tree, render: RenderTree<Tree>) => ServerRenderResult;
+
+/** Что нужно адаптеру, чтобы отрисовать остров на сервере. */
+interface RenderIslandOptions {
+    /** Контейнер острова — уже собранный, с активированными VM. */
+    container: Container;
+    /** Внешние заполнители слотов; для ядра непрозрачны, как и само дерево. */
+    slots?: Record<string, unknown>;
+}
 /**
  * Порт view-адаптера. Реализуется пакетом фреймворка (`@foxford/den-react` и его аналоги),
  * объявляется приложением через `defineLayer(ViewLayerToken, { adapter })`.
@@ -82,6 +136,18 @@ interface ViewAdapter {
      * @returns Компонент фреймворка — для ядра непрозрачен
      */
     createIsland(descriptor: IslandDescriptor): unknown;
+    /**
+     * Отрисовывает остров в разметку на сервере.
+     *
+     * Единственная операция острова, которую ядро не может сделать само: `renderToString` —
+     * функция конкретного фреймворка, а ядро view-агностично. Здесь же адаптер исполняет
+     * `serverRender` приложения, если тот объявлен, — тип дерева известен только адаптеру.
+     *
+     * @param descriptor - Дескриптор острова
+     * @param options - Контейнер острова и заполнители слотов
+     * @returns Разметка и вклад в `<head>` готовой разметкой
+     */
+    renderIsland(descriptor: IslandDescriptor, options: RenderIslandOptions): ServerRenderResult;
     /**
      * Ставит стратегию резолва `define*` во view (`installResolver` из `@foxford/den/adapter`).
      * У каждого фреймворка она своя: у React — хук поверх контекста контейнера, у Vue —
@@ -119,4 +185,4 @@ declare function viewAdapterOf(layer: ViewLayerDefinition): ViewAdapter;
  */
 declare function resolveViewAdapter(container: Container): ViewAdapter;
 
-export { type IslandDescriptor as I, type ViewAdapter as V, type ViewLayerDefinition as a, ViewLayerToken as b, resolveViewAdapter as r, viewAdapterOf as v };
+export { type IslandDescriptor as I, type RenderIslandOptions as R, type ServerRender as S, type ViewAdapter as V, type ViewLayerDefinition as a, ViewLayerToken as b, type RenderTree as c, type ServerRenderResult as d, resolveViewAdapter as r, viewAdapterOf as v };