@opetope/react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @opetope/react
+
+## 0.1.0
+
+Initial release. See the package README for the supported API and usage.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksei Berezin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# `@opetope/react`
+
+The React binding for Opetope models and UI contributions. [The specification](../runtime/docs/spec.md) §3 sets the package vocabulary.
+
+## Installation
+
+```sh
+npm install @opetope/core @opetope/runtime @opetope/react 'react@^19.0.0' 'react-dom@^19.0.0'
+```
+
+Use matching Opetope versions. For release candidates, append `@next` to every `@opetope/*` package in the command.
+The API is ESM-only; Node 20.19+ is required. Development check commands below apply to a contributor checkout.
+
+The normative EN/RU guides are shipped in `@opetope/runtime`: after installing it, open
+`node_modules/@opetope/runtime/docs/spec.md` or `spec.ru.md`; recipes are in `cookbook.md` and `cookbook.ru.md`.
+No GitHub access is needed to read those installed guides.
+
+## Hello UI
+
+```tsx
+import { defineModel } from '@opetope/core';
+import type { Call, Readable } from '@opetope/core';
+import { defineSlot, requiresModels, Slot, useModel } from '@opetope/react';
+
+const CounterModel = defineModel<{
+  readonly count: Readable<number>;
+  readonly increment: Call<void, void>;
+}>('example.counter.model');
+const CounterSlot = defineSlot<{ readonly label: string }>({ id: 'example.counter.slot' });
+
+const CounterButton = requiresModels([CounterModel])(({ label }: { readonly label: string }) => {
+  const {
+    count,
+    increment: { inFlight, lastError, run },
+  } = useModel(CounterModel, (model, { read }) => ({
+    count: read(model.count),
+    increment: model.increment,
+  }));
+
+  return (
+    <button disabled={inFlight} onClick={() => void run()}>
+      {lastError ? 'Retry' : `${label}: ${count}`}
+    </button>
+  );
+});
+
+function CounterArea() {
+  return <Slot props={{ label: 'Count' }} target={CounterSlot} />;
+}
+```
+
+A component gets neither a service, nor a class, nor a runtime ref. The contribution mount grants its feature's `own` models implicitly; the component or hook that reads a per-mount
+model declares it with `requiresModels`. `useModel` reads exactly that authority frame. `useCommand` returns `{ run, inFlight, result, lastError }`
+and always resolves the outcome, so a normal cancellation never becomes an unhandled rejection (D116).
+
+`run` is stable while the invoker stays the same; the returned object changes as `inFlight`, `result` or
+`lastError` changes. Destructure `run` for effect dependencies.
+
+The hook schedules nothing. Every `run` reaches the call, and the policy the call was created with decides what
+happens to it (D203). For an absolute value setter the model declares `policy: 'latest'` in `context.call`, and the
+newest input then replaces the waiting one there (D185). What the consumer keeps is its own: an already-aborted
+input signal is refused as `cancelled` without reaching the call, a run of an unmounted consumer is refused the same
+way, `inFlight` is true while any run this consumer started is unsettled, and every run carries its own callbacks
+and signal.
+
+For several commands use an object selection (D174):
+
+```tsx
+const { save, remove } = useCommands({ save: model.save, remove: other.remove });
+
+void save.run(input);
+const saving = save.inFlight;
+```
+
+Import `useCommands` from `@opetope/react`. Each selected field returns the same `CommandHook` as `useCommand`,
+with its own input/output types, status, result and error. Keys are local UI names; commands may come from
+different granted models. There is no second argument: each call carries its own policy.
+
+An inline object needs no `useMemo`. Reordering keys or updating a sibling preserves an unchanged field's object
+and `.run`. Adding or removing keys does not change the number of React hooks. Removing a key or replacing its
+command starts a fresh local status for that field; abandoned renders leave the
+committed selection intact. Two aliases of one Call have independent local statuses, just like two `useCommand`
+consumers; they use the same Call policy and mount command record (D197, D203). A group introduces no shared busy state, queue or transaction; controls that overwrite one value still
+need one semantic command. Only own enumerable properties are selected, including symbol keys.
+
+## Selecting data and commands
+
+`useModel(Declaration, (model, { read }) => ({ ... }))` combines explicit data selection and command consumers (D205, D214).
+
+A model selection can use a named interface without an index signature (D217). Its result is a flat data record;
+arrays, functions, constructors and built-in collection/date/promise objects are not selection records.
+`read(source)` returns its snapshot; `read(source, project)` returns a projection. Authentic Calls selected as record
+fields become the same `CommandHook` as `useCommands`, including independent alias statuses and stable `.run`.
+The one-argument form still returns the granted model; individual hooks remain available.
+
+Only explicitly read sources are subscribed, once per distinct Readable in the selection. Returned data fields are
+compared with `Object.is`; select scalar fields, spread a projected record into the selection, or return stable
+references. A newly allocated nested object is a changed field. The callback is pure: no hooks, commands or side effects.
+A read or selector error reaches the nearest React error boundary. Changing the selected sources or command keys
+changes their subscriptions/consumers at commit; an abandoned render cannot replace committed authority.
+
+The hook neither creates a model nor acquires a feature or retains a Resource. Use `useResource` when a consumer
+must keep a resource active. Combining hooks does not promise fewer source subscriptions or faster renders; a raw
+`useModel` import now also includes the selection implementation. There is no additional Call scheduler.
+
+## Application host
+
+The host opens a feature graph with `openApplication`. Ready features publish their UI contributions atomically;
+the ordinary `Slot` mounts them into consumer-owned targets:
+
+```tsx
+<Slot target={exampleFooterSlot} />
+<Slot target={exampleSettingsSlot} />
+```
+
+The application owns feature lifetimes; each feature's UI mounts through its contributions.
+
+## Feature demand boundary
+
+```tsx
+import { Slot } from '@opetope/react';
+import { FeatureBoundary, useFeatureRetry } from '@opetope/react/integration';
+
+function Retry() {
+  return <button onClick={useFeatureRetry()}>Try again</button>;
+}
+
+<FeatureBoundary demand={host} error={<Retry />} fallback={<Spinner />}>
+  <Slot props={{ itemId, onConfirmed }} target={confirmActionContentSlot} />
+</FeatureBoundary>;
+
+// or with render callbacks, when the ready instance itself is needed (D177)
+<FeatureBoundary
+  demand={host}
+  error={({ error, retry }) => <Failure error={error} onRetry={retry} />}
+  fallback={<Spinner />}
+>
+  {({ exports }) => <TasksResourceLease resource={exports.tasks}>{children}</TasksResourceLease>}
+</FeatureBoundary>;
+```
+
+`FeatureBoundary` consumes a `FeatureDemandSource` supplied by host integration. It holds the demand for the feature,
+shows the ready branch once that demand is ready and isolates `useFeatureRetry` inside the error subtree. A branch may be a node or a
+render callback: the callback of `children` receives the ready instance typed by the demand, the callback of `error`
+receives `{ error, retry }`, and only the branch that is shown runs. The callback needs no `useFeature` of its own,
+so a ready consumer does not acquire the demand a second time; hooks still live in child components, not in the
+callback. There is no separate hook for
+reading the error: the host passed it into `error` itself, so it knows it without a second word (D142). UI enters a feature through `Slot`: there is no
+root, no `ui` section and no second binding API any more (D85).
+
+## Contributions
+
+```tsx
+import { defineSlot, defineSwitchSlot, Slot } from '@opetope/react';
+
+const HeaderEnd = defineSlot<{ readonly mode: 'desktop' | 'phone' }>({ id: 'example.headerEnd' });
+const PageEnd = defineSwitchSlot<'home' | 'wallet', { readonly compact: boolean }>({
+  id: 'example.pageEnd',
+});
+
+function Header({ mode }: { readonly mode: 'desktop' | 'phone' }) {
+  return <Slot props={{ mode }} target={HeaderEnd} />;
+}
+
+function HomePageEnd() {
+  return <Slot props={{ compact: true }} target={PageEnd('home')} />;
+}
+```
+
+`defineSlot` creates an authentic target with an ordered set of contributions; `defineSwitchSlot` lazily creates and
+caches a stable target per route. `Slot` reads the atomic snapshot and renders every `{ Component }` in the authority
+frame of the instance that gave the contribution. The order and the stable key come from the contribution entries of the core, so
+React introduces neither a second comparator nor a second lifetime registry.
+
+`useResource(resource)` reads the atomic snapshot of a resource through `useSyncExternalStore` and holds one lease per
+mounted consumer. When the reference changes, the snapshot follows the new resource and effect cleanup releases the previous lease.
+
+Direct component props, a contribution's `props` adapter and its model's props `Readable` share the same
+mount-owned snapshot. Incoming slot props publish in layout before paint, so direct and adapted renders cannot
+mix new props with an old model snapshot. Model factory failures clean up partially created kernels.
+Models belong to commit: an abandoned render creates no model to clean up (D170, D188).
+StrictMode effect replay and Suspense hide/reveal preserve the committed model bundle and state. Only actual
+identity replacement or unmount releases it; a hidden unmount releases in a microtask after React has disconnected
+the layout effects (D209).
+
+Demand retry is scoped to the source identity. Replacing a boundary's demand source allows its new retry to run
+even if the previous source's retry is still pending.
+
+## Scenario tests and physical activity
+
+`createScenario(application, options)` from `@opetope/react/testing` opens the real application and its existing
+inspection session (D206, D215). Supply the normal `imports`/`conditions` and a test-owned
+`host.mount(Component)` adapter returning an `unmount()` handle. The package adds no DOM renderer or test-runner
+dependency. `scenario.mount(target, { props })` uses the published Slot contributions and returns
+`{ host, updateProps, unmount }`; `host` is the renderer's original result. Typed targets require `options.props`,
+while targets without props omit it, exactly as with `Slot` (D217). Fixture commands do not bypass authority.
+
+The synchronous constructor exposes `ready`, so a test can inspect a pending lazy body before readiness.
+`waitFor(snapshot => predicate, { label, timeoutMs, pollIntervalMs })` wakes on inspection changes and also polls
+external UI predicates; `notify()` wakes it after a controlled fixture update. The default deadline is 1000ms,
+with a 10ms predicate poll. A `ScenarioTimeoutError` carries the data-only snapshot, bounded history and observed
+conditions, feature phases, body loads, lane blockers and resource retention facts. It does not infer repository
+or network causes. `getSnapshot()` and `history()` use that same observation model; history defaults to 64 snapshots,
+activity to 256 records. Capacities accept integers from 1 to 10000. Do not replace predicates with a fixed number of ticks.
+
+`close()` fences application admission synchronously, unmounts all registered screens and joins their cleanup with
+physical application drain. Its deadline does not cancel cleanup: a later `close()` can await the same drain.
+A readiness deadline likewise leaves the application available for inspection and explicit cleanup.
+`ownership()` reports only registered runtime ownership, with `unknown` for missing, stale or truncated evidence;
+a workspace stale snapshot is complete only after the scenario witnessed successful physical cleanup. This permits
+a scoped zero-count assertion, without proving absence of arbitrary host, UI or GC leaks. Successful cleanup clears
+application imports and internal renderer references. A failed cleanup promise can retain original errors and retry
+capabilities; a caller that keeps `mounted.host` also keeps its own renderer result.
+
+The inspection graph/frame schema is `/3`, with optional `opetope.runtime-activity/1` snapshots. Within one session,
+a frame without `activity` preserves the previous activity; a full snapshot/reset without it clears that observation
+(D216). Activity-bearing frames replace the previous activity in full.
+Use matching runtime/devtools versions: `/2` readers reject the new revision. Activity identifies the execution,
+actual feature generation, physical Calls, exact current lane blockers, registered resource leases and load attempts.
+Host demand and UI models are unknown; stream observation covers state, not physical load identities. `freshness`
+and `truncated` distinguish a complete live view from a partial or detached one. A closed session is stale;
+`closed: true` requires successful physical application drain. No control authority or product payload is added.
+Activity output is bounded by record capacity. Snapshot collection still visits registered owners, executors and
+resources, so capacity does not bound traversal cost. Collection stops once truncation is proven;
+idle executors may still require traversal to establish completeness. Normal call dispatch allocates no diagnostic record with
+observation disabled. Graph frames remain bounded by the existing ring capacity.
+
+## Testing
+
+`@opetope/react/testing` exports component fixtures and application scenarios:
+
+- `renderSlot(target, { contribution, models, props })` mounts the published target or one fixture contribution;
+- `command(run)` produces an authentic `Call` for a model fixture.
+
+The `renderSlot` harness returns `Slot` and `updateProps`: there are no roots and no fixtures for them, UI enters the
+application as contributions (D85).
+
+## Word map and entries
+
+| Entry                        | What it holds                                                                                                                                                                                                                                                      |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@opetope/react`             | `useModel`, `useCommand`, `useCommands`, `useReadable`, `useSelector`, `useResource`, `requiresModels`, `defineSlot`, `defineSwitchSlot`, `Slot`, `ContributionError`; types `SlotTarget`, `SwitchSlotTarget`, `SlotContribution`, `CommandHook`, `CommandOutcome` |
+| `@opetope/react/integration` | `FeatureBoundary`, `useFeature`, `useFeatureRetry`, `FeatureBoundaryError` for the integration layer; types `FeatureBoundaryProps`, `FeatureDemandSource`, `FeatureDemandState`, `FeatureDemandResult`, `FeatureDemandLease`                                       |
+| `@opetope/react/testing`     | `renderSlot`, `command`, `createScenario`, `ScenarioTimeoutError` and fixture/scenario types; tests only                                                                                                                                                           |
+
+`Model` is a typed key for a record of `Readable`, `Call` and readable factories that UI components consume.
+The constructors of the integration entry are not re-exported from the safe entry and cannot come back into
+`ui/models/data/contracts` through a local barrel of a feature.
+
+## Laws
+
+- `useModel(declaration)` reads only the models declared by the contribution;
+- one committed contribution owns its model frame until unmount or retire;
+- an abandoned concurrent render holds no frame;
+- `useCommand` does not subscribe to the invoker: the observable state of a call lies in a `Readable` of the model;
+- the `cancelled` outcome moves neither `result` nor `lastError`, and it is only the `CallError` codes `cancelled`
+  and `closed`; a call to a weak port with no provider (`unavailable`) and a rejected publication
+  (`publication-rejected`) arrive as the `failed` outcome and settle in `lastError` (D138);
+- `useSelector` keeps the selected reference when something else changed;
+- closing and unmounting synchronously fence new calls and release the references of the frame.
+
+## Compatibility contract
+
+The ESM of the package is built for Chrome 82+, Firefox 110+, Safari/iOS 15+, Android 82+ and Node 20.19+ and requires
+the peer `react >=19.0.0 <20` (D251). React and ReactDOM are peers of the host, not built-in polyfills. The raw modules are
+executed by an HTTP import smoke test with a local bundle of the peers; historical browser builds are checked only by an external farm.

package/README.ru.md

@@ -0,0 +1,266 @@
+# `@opetope/react`
+
+React-привязка для моделей и UI-вкладов Opetope. Словарь пакета задаёт §3 [спецификации](../runtime/docs/spec.ru.md).
+
+## Установка
+
+```sh
+npm install @opetope/core @opetope/runtime @opetope/react 'react@^19.0.0' 'react-dom@^19.0.0'
+```
+
+Используйте согласованные версии Opetope. Для release candidate добавьте `@next` каждому пакету `@opetope/*` в команде.
+API поставляется только в ESM; требуется Node 20.19+. Команды разработки ниже относятся к contributor checkout.
+
+Нормативные руководства EN/RU поставляются в `@opetope/runtime`: после его установки откройте
+`node_modules/@opetope/runtime/docs/spec.md` или `spec.ru.md`; рецепты находятся в `cookbook.md` и `cookbook.ru.md`.
+Для чтения установленных руководств доступ к GitHub не нужен.
+
+## Hello UI
+
+```tsx
+import { defineModel } from '@opetope/core';
+import type { Call, Readable } from '@opetope/core';
+import { defineSlot, requiresModels, Slot, useModel } from '@opetope/react';
+
+const CounterModel = defineModel<{
+  readonly count: Readable<number>;
+  readonly increment: Call<void, void>;
+}>('example.counter.model');
+const CounterSlot = defineSlot<{ readonly label: string }>({ id: 'example.counter.slot' });
+
+const CounterButton = requiresModels([CounterModel])(({ label }: { readonly label: string }) => {
+  const {
+    count,
+    increment: { inFlight, lastError, run },
+  } = useModel(CounterModel, (model, { read }) => ({
+    count: read(model.count),
+    increment: model.increment,
+  }));
+
+  return (
+    <button disabled={inFlight} onClick={() => void run()}>
+      {lastError ? 'Retry' : `${label}: ${count}`}
+    </button>
+  );
+});
+
+function CounterArea() {
+  return <Slot props={{ label: 'Count' }} target={CounterSlot} />;
+}
+```
+
+Компонент не получает ни сервис, ни класс, ни ref рантайма. Монтирование вклада неявно выдаёт модели `own` его фичи;
+компонент или хук, читающий per-mount модель, объявляет её через `requiresModels`. `useModel` читает ровно этот кадр
+авторитета. `useCommand` отдаёт `{ run, inFlight, result, lastError }`
+и всегда resolve-ит исход, поэтому штатная отмена не становится unhandled rejection (D116).
+
+`run` стабилен, пока invoker тот же; возвращённый объект меняется вместе с `inFlight`, `result` или `lastError`.
+Для зависимостей эффекта берите `run` деструктуризацией.
+
+Хук ничего не планирует. Каждый `run` доходит до вызова, и решает политика, с которой вызов создан (D203). Для
+setter абсолютного значения модель объявляет `policy: 'latest'` в `context.call`, и новый вход заменяет ожидающий
+именно там (D185). За потребителем остаётся своё: уже отменённый входной signal отвергается как `cancelled`, не
+доходя до вызова, `run` размонтированного потребителя отвергается так же, `inFlight` истинен, пока не завершился
+хоть один начатый им прогон, и у каждого прогона свои callbacks и signal.
+
+Для нескольких команд используйте объектный выбор (D174):
+
+```tsx
+const { save, remove } = useCommands({ save: model.save, remove: other.remove });
+
+void save.run(input);
+const saving = save.inFlight;
+```
+
+Импортируйте `useCommands` из `@opetope/react`. Каждое поле возвращает прежний `CommandHook`, как `useCommand`,
+со своими типами входа/выхода, статусом, результатом и ошибкой. Ключи — локальные имена UI; команды могут быть
+из разных разрешённых моделей. Второго аргумента нет: политика есть у каждого вызова.
+
+Объекту прямо в рендере не нужен `useMemo`. Перестановка ключей и обновление соседнего поля сохраняют объект
+неизменившегося поля и `.run`. Добавление и удаление ключей не меняет число React hooks. Удаление ключа или
+замена его команды начинает новый локальный статус этого поля; отброшенный
+рендер не меняет текущий выбор. Два псевдонима одного Call имеют независимые локальные статусы, как два потребителя
+`useCommand`; они используют одну политику Call и одну command-запись монтирования (D197, D203). Группа не вводит общий busy, очередь или транзакцию; контролам, перезаписывающим одно значение,
+по-прежнему нужна одна смысловая команда. Выбираются только собственные enumerable-поля, включая symbol-ключи.
+
+## Выбор данных и команд
+
+`useModel(Declaration, (model, { read }) => ({ ... }))` объединяет явный выбор данных и command consumers (D205, D214).
+
+Результат выбора модели может быть именованным interface без index signature (D217). Результат — плоская запись данных;
+arrays, functions, constructors и встроенные объекты коллекций, дат и promises не являются selection records.
+`read(source)` возвращает снимок; `read(source, project)` — проекцию. Authentic Calls, выбранные полями record,
+превращаются в тот же `CommandHook`, что у `useCommands`, с независимыми статусами aliases и стабильным `.run`.
+Форма с одним аргументом по-прежнему возвращает выданную модель; отдельные hooks сохраняются.
+
+Подписка создаётся только на явно прочитанные источники, одна на каждый различный Readable внутри selection.
+Поля данных сравниваются через `Object.is`: выбирайте скаляры, раскрывайте проекцию record в selection или
+возвращайте стабильные ссылки. Новый вложенный объект считается изменившимся полем. Callback чистый:
+без hooks, команд и side effects. Ошибка read/selector попадает в ближайший React error boundary.
+Изменение источников и ключей команд применяется в commit; abandoned render не меняет действующие полномочия.
+
+Hook не создаёт модель, не приобретает feature и не удерживает Resource. Для активного удержания ресурса
+используйте `useResource`. Объединение hooks не обещает меньше подписок или более быстрый render;
+импорт обычного `useModel` теперь также включает реализацию selection. Дополнительного scheduler для Call нет.
+
+## Application host
+
+Хост открывает граф фич через `openApplication`. Готовые фичи атомарно публикуют UI-вклады;
+обычный `Slot` монтирует их в consumer-owned целях:
+
+```tsx
+<Slot target={exampleFooterSlot} />
+<Slot target={exampleSettingsSlot} />
+```
+
+Приложение владеет временем жизни фич; UI каждой фичи монтируется через её вклады.
+
+## Граница спроса на фичу
+
+```tsx
+import { Slot } from '@opetope/react';
+import { FeatureBoundary, useFeatureRetry } from '@opetope/react/integration';
+
+function Retry() {
+  return <button onClick={useFeatureRetry()}>Try again</button>;
+}
+
+<FeatureBoundary demand={host} error={<Retry />} fallback={<Spinner />}>
+  <Slot props={{ itemId, onConfirmed }} target={confirmActionContentSlot} />
+</FeatureBoundary>;
+
+// или с render-колбэками, когда нужен сам готовый экземпляр (D177)
+<FeatureBoundary
+  demand={host}
+  error={({ error, retry }) => <Failure error={error} onRetry={retry} />}
+  fallback={<Spinner />}
+>
+  {({ exports }) => <TasksResourceLease resource={exports.tasks}>{children}</TasksResourceLease>}
+</FeatureBoundary>;
+```
+
+`FeatureBoundary` принимает `FeatureDemandSource` от интеграции с хостом. Он держит спрос на фичу,
+показывает готовую ветвь после готовности спроса и изолирует `useFeatureRetry` в поддереве ошибки. Ветвь может быть узлом или
+render-колбэком: колбэк `children` получает готовый экземпляр, типизированный по `demand`, колбэк `error` получает
+`{ error, retry }`, и выполняется только показанная ветвь. Своего `useFeature` колбэку не нужно, поэтому готовый
+потребитель не берёт спрос второй раз; хуки по-прежнему живут в дочерних компонентах, а не в колбэке. Отдельного хука для чтения ошибки
+нет: хост сам передал её в `error`, поэтому знает её без второго слова (D142). UI входит в фичу через `Slot`: ни
+корня, ни секции `ui`, ни второго API привязки больше нет (D85).
+
+## Contributions
+
+```tsx
+import { defineSlot, defineSwitchSlot, Slot } from '@opetope/react';
+
+const HeaderEnd = defineSlot<{ readonly mode: 'desktop' | 'phone' }>({ id: 'example.headerEnd' });
+const PageEnd = defineSwitchSlot<'home' | 'wallet', { readonly compact: boolean }>({
+  id: 'example.pageEnd',
+});
+
+function Header({ mode }: { readonly mode: 'desktop' | 'phone' }) {
+  return <Slot props={{ mode }} target={HeaderEnd} />;
+}
+
+function HomePageEnd() {
+  return <Slot props={{ compact: true }} target={PageEnd('home')} />;
+}
+```
+
+`defineSlot` создаёт подлинную цель с упорядоченным множеством вкладов; `defineSwitchSlot` лениво создаёт и
+кеширует стабильную цель на каждый маршрут. `Slot` читает атомарный снимок и рендерит каждый `{ Component }` в кадре
+авторитета того экземпляра, который вклад дал. Порядок и стабильный ключ приходят из записей вкладов ядра, поэтому
+React не вводит второй компаратор и второй реестр времени жизни.
+
+`useResource(resource)` читает атомарный снимок ресурса через `useSyncExternalStore` и держит один lease на
+смонтированного потребителя. При смене ссылки snapshot следует новому ресурсу, а cleanup эффекта освобождает предыдущий lease.
+
+Прямые пропсы компонента, `props`-адаптер вклада и props-`Readable` его модели используют один снимок
+монтирования. Входящие пропсы слота публикуются в layout до paint, поэтому прямой и адаптированный рендеры
+не смешивают новые пропсы со старым снимком модели. Отказ фабрики модели убирает частично созданный kernel.
+Модели принадлежат коммиту: брошенный рендер не создаёт модель, которую пришлось бы убирать (D170, D188).
+Повтор эффектов StrictMode и скрытие/раскрытие Suspense сохраняют закоммиченный набор моделей и состояние.
+Только реальная замена идентичности или размонтирование освобождает его; при скрытом размонтировании это делает
+микрозадача после того, как React отключил layout-эффекты (D209).
+
+Retry спроса привязан к источнику. После замены источника boundary новый retry может начаться, даже если retry
+старого ещё не завершён.
+
+## Сценарные тесты и физическая активность
+
+`createScenario(application, options)` из `@opetope/react/testing` открывает настоящее приложение и его существующую
+inspection session (D206, D215). Передайте обычные `imports`/`conditions` и принадлежащий тесту адаптер
+`host.mount(Component)`, возвращающий handle с `unmount()`. Пакет не добавляет зависимость от DOM renderer или test runner.
+`scenario.mount(target, { props })` использует опубликованные Slot contributions и возвращает
+`{ host, updateProps, unmount }`; `host` — исходный результат renderer. Typed targets требуют `options.props`,
+а targets без props опускают его, как в `Slot` (D217). Fixtures не обходят authority команд.
+
+Синхронный конструктор возвращает `ready`, поэтому pending lazy body можно исследовать до готовности.
+`waitFor(snapshot => predicate, { label, timeoutMs, pollIntervalMs })` просыпается от inspection и дополнительно
+опрашивает predicates внешнего UI; `notify()` будит его после изменения управляемой fixture. По умолчанию deadline
+равен 1000ms, polling predicate — 10ms. `ScenarioTimeoutError` содержит data-only snapshot, ограниченную историю и
+наблюдаемые conditions, фазы feature, body load, lane blockers и удержания ресурсов. Причины внутри repository
+или сети не выводятся из догадок. `getSnapshot()` и `history()` используют ту же модель наблюдения; по умолчанию
+хранятся 64 снимка, activity ограничена 256 записями. Capacities — целые от 1 до 10000.
+Не заменяйте predicates фиксированным числом ticks.
+
+`close()` синхронно ставит fence admission приложения, размонтирует зарегистрированные экраны и ждёт их cleanup
+вместе с physical application drain. Deadline не отменяет cleanup: последующий `close()` может дождаться того же drain.
+Deadline готовности также оставляет приложение доступным для inspection и явного закрытия.
+`ownership()` описывает только зарегистрированное владение runtime; при отсутствующих, stale или усечённых данных
+возвращается `unknown`. Терминальный stale-снимок считается полным лишь после подтверждённого сценарием успешного
+физического cleanup. Это допускает проверку нулевых счётчиков в данном scope, но не доказывает отсутствие произвольных
+host/UI/GC-утечек. Успешный cleanup очищает imports приложения и внутренние ссылки на renderer. Promise отказавшего
+cleanup может удерживать исходные ошибки и retry capabilities; сохранённый пользователем `mounted.host` удерживает его renderer result.
+
+Inspection graph/frame имеют схему `/3` и optional snapshots `opetope.runtime-activity/1`. В пределах одной session
+frame без `activity` сохраняет предыдущую activity; полный snapshot/reset без этого поля очищает наблюдение (D216).
+Frame с `activity` заменяет предыдущую activity целиком.
+Используйте согласованные версии runtime/devtools: readers `/2` отвергают новую revision. Activity указывает execution,
+фактическое поколение feature, физические Calls, точных текущих lane blockers, зарегистрированные leases и попытки загрузок.
+Спрос хоста и UI-модели неизвестны; у stream наблюдается state, но не физические identities загрузок. `freshness`
+и `truncated` отличают полное live-наблюдение от усечённого или отключённого. Закрытая session имеет stale-снимок;
+`closed: true` требует успешного физического drain приложения. Control authority и продуктовые payload не добавляются.
+Размер activity ограничен capacity записей. Сбор снимка обходит зарегистрированных owners, executors и resources,
+поэтому capacity не ограничивает стоимость обхода. Сбор останавливается после доказанного truncation;
+idle executors могут требовать обхода, чтобы подтвердить полноту данных. Обычный call dispatch не создаёт диагностических записей при
+выключенном наблюдении. Frames ограничены существующей ring capacity.
+
+## Testing
+
+`@opetope/react/testing` экспортирует fixtures компонентов и сценарии приложения:
+
+- `renderSlot(target, { contribution, models, props })` монтирует опубликованную цель либо один вклад-фикстуру;
+- `command(run)` выдаёт подлинный `Call` для фикстуры модели.
+
+Харнесс `renderSlot` отдаёт `Slot` и `updateProps`: корней и их фикстур больше нет, UI входит в приложение
+вкладами (D85).
+
+## Карта слов и входы
+
+| Вход                         | Что содержит                                                                                                                                                                                                                                                      |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@opetope/react`             | `useModel`, `useCommand`, `useCommands`, `useReadable`, `useSelector`, `useResource`, `requiresModels`, `defineSlot`, `defineSwitchSlot`, `Slot`, `ContributionError`; типы `SlotTarget`, `SwitchSlotTarget`, `SlotContribution`, `CommandHook`, `CommandOutcome` |
+| `@opetope/react/integration` | `FeatureBoundary`, `useFeature`, `useFeatureRetry`, `FeatureBoundaryError` для integration-слоя; типы `FeatureBoundaryProps`, `FeatureDemandSource`, `FeatureDemandState`, `FeatureDemandResult`, `FeatureDemandLease`                                            |
+| `@opetope/react/testing`     | `renderSlot`, `command`, `createScenario`, `ScenarioTimeoutError` и типы fixtures/scenarios; только для тестов                                                                                                                                                    |
+
+`Model` — типизированный ключ записи из `Readable`, `Call` и фабрик readable, которую используют UI-компоненты.
+Конструкторы integration-входа не переэкспортируются из безопасного входа и не могут вернуться в
+`ui/models/data/contracts` через локальный barrel фичи.
+
+## Законы
+
+- `useModel(declaration)` читает только модели, объявленные вкладом;
+- один закоммиченный вклад владеет своим кадром моделей до размонтирования или retire;
+- брошенный concurrent-рендер кадр не удерживает;
+- `useCommand` не подписывается на invoker: наблюдаемое состояние вызова лежит в `Readable` модели;
+- исход `cancelled` не двигает ни `result`, ни `lastError`, и это только коды `CallError` `cancelled`
+  и `closed`; вызов слабого порта без провайдера (`unavailable`) и отклонённая публикация
+  (`publication-rejected`) приходят исходом `failed` и оседают в `lastError` (D138);
+- `useSelector` сохраняет выбранную ссылку, когда изменилось что-то другое;
+- закрытие и размонтирование синхронно фенсят новые вызовы и освобождают ссылки кадра.
+
+## Compatibility contract
+
+ESM пакета собирается для Chrome 82+, Firefox 110+, Safari/iOS 15+, Android 82+ и Node 20.19+ и требует peer
+`react >=19.0.0 <20` (D251). React и ReactDOM это peers хоста, а не встроенные полифилы. Сырые модули исполняет smoke импорта
+по HTTP с локальным бандлом peer-ов; исторические сборки браузеров проверяет только внешняя ферма.

package/dist/command-hook-controller.d.ts

@@ -0,0 +1,33 @@
+import type { CallRunOptions } from '@opetope/core/internal';
+import type { CommandOutcome } from './command.js';
+type CommandRunOptions<Output> = Readonly<{
+    onFailure?: (error: unknown) => PromiseLike<void> | void;
+    onSuccess?: (value: Output) => PromiseLike<void> | void;
+    signal?: AbortSignal;
+}>;
+type CommandRun<Input, Output> = [Input] extends [void] ? (input?: Input, options?: CommandRunOptions<Output>) => Promise<CommandOutcome<Output>> : (input: Input, options?: CommandRunOptions<Output>) => Promise<CommandOutcome<Output>>;
+type CommandInvoker = Readonly<{
+    run: (input: never, options?: CallRunOptions<unknown>) => Promise<unknown>;
+}>;
+type CommandNotification<Output> = (inFlight: boolean, outcome?: CommandOutcome<Output>) => void;
+/**
+ * D203: the consumer keeps a status, not a schedule. Every `run` reaches the call, and the policy the call was
+ * created with — `queue`, `latest`, `parallel`, `once`, `singleFlight` — decides what happens to it. What stays
+ * local is what only this consumer knows: whether it is mounted, its own input signal, and the outcome it shows.
+ */
+declare class CommandHookController<Input, Output> {
+    private readonly invoker;
+    readonly run: CommandRun<Input, Output>;
+    private inFlight;
+    private notify;
+    constructor(invoker: CommandInvoker);
+    attach(notify: CommandNotification<Output>): () => void;
+    synchronize(): void;
+    private aborted;
+    private cancelledInput;
+    private finish;
+    private invoke;
+    private start;
+}
+export { CommandHookController };
+export type { CommandInvoker, CommandRun };

package/dist/command-hook.d.ts

@@ -0,0 +1,13 @@
+import type { Call } from '@opetope/core';
+import type { CommandRun } from './command-hook-controller.js';
+interface CommandHookStatus<Output> {
+    readonly inFlight: boolean;
+    readonly lastError: unknown | null;
+    readonly result: Output | undefined;
+}
+type CommandHook<Input, Output> = CommandHookStatus<Output> & {
+    readonly run: CommandRun<Input, Output>;
+};
+declare function useCommand<Input, Output>(command: Call<Input, Output>): CommandHook<Input, Output>;
+export { useCommand };
+export type { CommandHook };

package/dist/command.d.ts

@@ -0,0 +1,26 @@
+import type { Call } from '@opetope/core';
+/**
+ * A bound command is the authentic `Call` the model field declares, so the common path adds no wrapper. Observable
+ * call state belongs to the model as a `Readable` field (D71), so a binding carries no mode.
+ */
+type Command<Input, Output> = Call<Input, Output>;
+type CommandBinding<Input, Output> = Command<Input, Output>;
+type CommandOutcome<Output> = {
+    readonly error: unknown;
+    readonly status: 'failed';
+} | {
+    readonly reason: unknown;
+    readonly status: 'cancelled';
+} | {
+    readonly status: 'ok';
+    readonly value: Output;
+};
+type AnyCommandBinding = CommandBinding<never, unknown>;
+type CommandBindingDefinition<Input, Output> = {
+    readonly target: Call<Input, Output>;
+};
+declare function bindCommand<Input, Output>(target: Call<Input, Output>): CommandBinding<Input, Output>;
+declare function getCommandBindingDefinition<Input, Output>(binding: Call<Input, Output>): CommandBindingDefinition<Input, Output>;
+declare function isCommandBinding(value: unknown): value is AnyCommandBinding;
+export { bindCommand, getCommandBindingDefinition, isCommandBinding };
+export type { Command, CommandOutcome };