@opetope/react 0.11.0 → 0.12.1

package/README.md

@@ -1,30 +1,33 @@
 # `@opetope/react`
 
-The React binding for Opetope models and UI contributions. [The specification](../runtime/docs/spec.md) §3 sets the package vocabulary.
+React hooks and slots for Opetope models. A contribution grants the models its UI may read; hooks subscribe to selected data and expose commands with local status.
 
 ## Installation
 
 ```sh
-npm install @opetope/core @opetope/runtime @opetope/react 'react@^19.0.0' 'react-dom@^19.0.0'
+npm install --save-exact @opetope/core @opetope/runtime @opetope/react 'react@^19' 'react-dom@^19'
 ```
 
-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.
+Use matching exact Opetope versions; for release candidates, install every Opetope package from `@next`.
+Packages are ESM-only and support Node 20.19+. React integrations support React and React DOM 19.
 
-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.
+## Example
 
-## Hello UI
+This focused example shows the package boundary. [Start](../runtime/docs/start.md) includes a complete
+feature, host, React entry and cleanup in one visible module.
+
+<!--example id="doc-readme-react-0"
+/* … */
+-->
 
 ```tsx
 import { defineModel } from '@opetope/core';
-import type { Call, Readable } from '@opetope/core';
+import type { Command, Readable } from '@opetope/core';
 import { defineSlot, requiresModels, Slot, useModel } from '@opetope/react';
 
 const CounterModel = defineModel<{
   readonly count: Readable<number>;
-  readonly increment: Call<void, void>;
+  readonly increment: Command<void, void>;
 }>('example.counter.model');
 const CounterSlot = defineSlot<{ readonly label: string }>('example.counter.slot');
 
@@ -39,7 +42,7 @@ const CounterButton = requiresModels([CounterModel])(({ label }: { readonly labe
 
   return (
     <button disabled={inFlight} onClick={() => void run()}>
-      {outcome?.status === 'failed' ? 'Retry' : `${label}: ${count}`}
+      {outcome?.kind === 'failed' ? 'Retry' : `${label}: ${count}`}
     </button>
   );
 });
@@ -49,364 +52,42 @@ function CounterArea() {
 }
 ```
 
-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, outcome }` and always resolves the outcome, so a normal cancellation never becomes an unhandled
-rejection (D116, D292).
-
-`outcome` is the last settled non-cancelled outcome of this consumer: `ok` takes the place of a previous `failed`
-and a `failed` the place of a previous `ok`, a `cancelled` outcome moves nothing, and starting a run clears nothing,
-so a failure stays readable while the retry is in flight. Before the first settle it is `undefined`. Read it through
-its discriminant — `outcome?.status === 'failed' ? outcome.error : null`.
-
-A command without input binds to an event through an arrow: `onClick={() => void logout.run()}`. The arrow is what
-keeps the React event out of the Call and the promise from hanging; `onClick={logout.run}` does not compile, because
-a `MouseEvent` is not a `void` input. Use `run(input, options?)` for data, an outcome, callbacks or a per-run signal.
-Where a lint config bans an inline arrow prop (`react-perf/jsx-no-new-function-as-prop`, `react/jsx-no-bind`), hoist
-it with `useCallback(() => void logout.run(), [logout.run])`: the dependency is `run`, never the hook object (D290).
-
-`run` is stable while the invoker stays the same; the returned object is a snapshot of the render it was read in and
-changes as `inFlight` or `outcome` changes, so an effect or a memo depends on `run` and never on the hook — the rule
-`opetope/no-command-in-deps` holds this for the author (D290). A `run` captured from a replaced or unmounted
-consumer is fenced; it does not start work on the replacement.
-
-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.
-
-To share equivalent pending or running work, the model declares `dedupe: true` or `dedupe: input => key`
-on `context.call`. Sharing keeps the first input and each caller's independent cancellation; neither form may
-be combined with `latest` (D277). These are Call options, not hook options.
-
-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 and its own `inFlight` and `outcome`. Keys are local UI names; commands may come from
-different granted models. There is no second argument: each call carries its own policy. Its own case is a key set
-the component does not know in advance — hooks are not called in a loop; a fixed set is `useCommand` per word or one
-`useModel` selection. It is proven by the packaged consumer of `ci:pack` and is a candidate to leave this entry
-until a second application is measured (D301).
-
-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`.
-A single selected command needs no nested hooks:
-
-```tsx
-const { logout } = useModel(AuthModel, auth => ({ logout: auth.logout }));
-return (
-  <button disabled={logout.inFlight} onClick={() => void logout.run()}>
-    Log out
-  </button>
-);
-```
-
-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. It leases exactly the resources its selection names as
-values — that field answers a `ResourceHook`, and one lease per Resource identity covers the mount even when two
-keys name one Resource (D321, D359) — and nothing else: a
-`read(resource.state)` leases nothing, and neither does the one-argument form. 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).
-
-Both the boundary and the bare `useFeature` are exercised by the packaged consumer of `ci:pack`, which checks the
-law they share: one lease per mount, kept across a settled `retry` and released on unmount. `useFeature` is the
-hook half used where a host renders the readiness itself, and it is a candidate to leave this entry until a second
-application is measured; `FeatureBoundary` is not a pair with `ContributionBoundary` and stays (D301).
-
-## Contributions
-
-```tsx
-import { defineSlot, defineSwitchSlot, Slot } from '@opetope/react';
-
-const HeaderEnd = defineSlot<{ readonly mode: 'desktop' | 'phone' }>('example.headerEnd');
-const PageEnd = defineSwitchSlot<'home' | 'wallet', { readonly compact: boolean }>('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. The packaged consumer of `ci:pack`
-exercises that caching and routes one contribution through it (D301).
-
-`useResource(resource)` answers `{ invalidate, pagination, refresh, retry, state }`: the `ResourceState` through
-`useSyncExternalStore`, the lease `resource.acquire()` answers taken in a commit effect for as long as the component
-is mounted, and the three verbs as ordinary `CommandHook` consumers (D359). An interrupted render therefore opens
-nothing, and when the reference changes the state follows the new Resource while the effect cleanup releases the
-previous lease. The number of React hooks does not depend on the Resource: a declaration without `pagination`
-subscribes to a constant source and keeps a `loadNext` that answers `skipped`, while a declaration that carried the
-capability answers `pagination` as `{ loadNext, state }` (D356). A field of a `useModel` selection whose value is a
-Resource answers the same hook and takes the same lease, so a model declares no `Call<void, void>` around
-`resource.refresh()` to give a button its `inFlight`. `useReadable(resource)` is a compile error, because a Resource
-is not a `Readable`; `useReadable(resource.state)` and a `read(resource.state)` in a selector stay passive and lease
-nothing — observing and holding are independent questions, so a selector that reads the state and a `useResource`
-beside it subscribe twice (D349). The compile-checked example of specification §2.13 shows both sides of that
-(D301, D321).
-
-`refresh.run()`, `retry.run()` and `invalidate.run()` reach the Resource, which is owned by the model that declared
-it: `inFlight` is true until the outcome of the operation settles, `outcome` carries that `ResourceOperationOutcome`
-as the `value` of an `ok` status, and `run(undefined, { signal })` cancels the wait of this consumer and not the work
-the model owns. Two consumers of one Resource keep separate statuses, and `run` keeps its identity while the Resource
-does. A render that caught up with retirement renders the terminal record — `idle` with reason `retired` for a Resource
-a model owns, `unleased` for a feature's facade, which is a reference that outlives the instance — and unmounts,
-releasing its lease (D359, D364). Nothing here refuses a read because a lifetime ended: a source whose owner retired
-stops and keeps answering its last value, so `useReadable`, `useSelector` with an inline selector and a selection's
-`read` each read on and need no memory of their own. A refusal that remains is work that failed — a state that
-failed, a broken pagination cursor — and it still reaches the render.
-
-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.
+## Documentation
 
-Every mount is an error boundary of its own contribution (D256). A render or commit that throws stops there, is
-reported to the feature that published the contribution, and leaves the other mounts of the target untouched.
-`ContributionBoundary` states once, above every slot, what a failed mount shows:
-
-```tsx
-import { ContributionBoundary } from '@opetope/react/integration';
-
-<ContributionBoundary error={({ error, retry }) => <FailedContribution error={error} onRetry={retry} />}>
-  <Slot target={applicationSurface} />
-</ContributionBoundary>;
-```
+The [reference](../runtime/docs/reference/react.md) owns the detailed contract, options and failure semantics.
+[Guides](../runtime/docs/guides/index.md) show individual tasks. Documentation is shipped with
+`@opetope/runtime` in `docs/`, so an installed application can read it without access to this repository.
 
-`error` takes a node or a callback of `{ contribution, error, feature, retry, target }`, the failure shape of
-`FeatureBoundary` plus the identity of what failed: `contribution` is the published entry `<feature>.<provides key>`
-and `target` is the slot, so one branch can answer by surface. `retry` remounts the contribution, so its models are
-created again. The reporter of the publishing feature receives the same identity on a `ContributionError` whose
-`cause` is the original error, with code `render-failed` or `error-content-failed`. Without the provider a failed mount renders nothing — containment
-never depends on it. Error content that throws is contained the same way and reported, never escalated.
-
-## 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.
-
-As with `openApplication`, omit `conditions` when no enabled feature requires a host-bound condition. Conditions
-computed through `from`/`select` bind automatically; external conditions still require their sources (D271).
-
-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 lease 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 schemas are `opetope.devtools-graph/5` and `opetope.devtools-frame/5`, with optional
-`opetope.runtime-activity/4` snapshots (D266, D275, D344, D358). 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: previous graph/frame and activity revisions are rejected; weak-edge presence requires graph `/5` and frame `/4`. Activity identifies the execution,
-actual feature generation, physical Calls, exact current lane blockers, and for every registered Resource its
-`kind`, `lifetime`, `epoch`, `state`, `activity` with its `operation`, `leases`, `subscribers`, `pagination` and the
-`epoch` of each physical load — there is no `attempt` and no numeric generation, because a Resource runs one logical
-attempt and recovery belongs to the transport (D358). Host demand and UI models are unknown. `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, and re-exports
-`@opetope/runtime/testing` — which in turn re-exports `@opetope/core/testing` — so a React test names one entry
-(D285):
-
-- `renderSlot(target, { contribution, models, props })` mounts the published target or one fixture contribution;
-- `command(run)` produces an authentic `Call` for a model fixture, plus the contribution binding a mount reads;
-- `runCall(target, input?, options?)` executes an existing authentic `Call` without mounting React (D261);
-- `testReadable(initial)`, `testResourceEpoch()`, `openModel`, `settled`, `waitFor`, `yieldTurn` and `eventually`
-  come from the entries below, for the part of a test that has no UI in it — `testResourceEpoch()` is what a
-  component fixture writing a `ResourceState` by hand puts in its `epoch` (D362).
-
-A test that renders nothing should import `@opetope/runtime/testing` directly: `renderSlot` and the binding half of
-`command` are all that needs React here. The Call a fixture mints is the `command` of `@opetope/core/testing`
-(D300), and this word is the one name of the re-export chain that does not pass through: the React `command`
-shadows it with the stronger one.
-
-The `renderSlot` harness returns `Slot` and `updateProps`: there are no roots and no fixtures for them, UI enters the
-application as contributions (D85). It is not a test spelling of `<Slot>` — it mounts a fixture and takes a
-`reporter`, because a component test has no feature to report to — and the packaged consumer of `ci:pack` mounts it
-from the real archive (D301).
-
-A test that previously mounted `useCommand` only to invoke a Call can use `runCall` directly. The result is the
-Call's output, while a UI test still checks the `CommandOutcome` returned by the mounted consumer:
-
-```ts
-import assert from 'node:assert/strict';
-import { defineModel } from '@opetope/core';
-import type { Call } from '@opetope/core';
-import { defineFeature, openFeature } from '@opetope/runtime';
-import { runCall } from '@opetope/react/testing';
-
-const Arithmetic = defineModel<{ readonly double: Call<number, number> }>('example.testing.model');
-const arithmetic = defineFeature('example.testing.arithmetic', {
-  own: ({ model }) => ({
-    arithmetic: model(Arithmetic, context => ({
-      double: context.call((input: number) => input * 2),
-    })),
-  }),
-  exports: ({ own }) => ({ double: own.arithmetic.double }),
-});
-const instance = openFeature(arithmetic, { imports: {}, reporter: () => undefined });
-try {
-  const ready = await instance.ready;
-  const result = await runCall(ready.exports.double, 3);
-  assert.equal(result, 6);
-} finally {
-  await instance.close();
-}
-```
+For a contributor checkout, use `npm run ci:type --workspace @opetope/react` and
+`npm run ci:test --workspace @opetope/react` where provided. The root `npm run check` performs full acceptance;
+[contributor commands](../runtime/docs/maintainers/contributing.md) describe the build and package checks.
 
-`runCall` returns `Promise<Output>` and preserves the Call's original errors and cancellation rejections. It adds no
-UI status or outcome wrapper, scheduling policy, model creation or cleanup lifetime. The existing Call retains its
-owner, lane and retirement rules; the test closes the instance it opened, including after failed readiness.
-A void Call can use `runCall(target)`. Options always occupy the third argument:
-`runCall(target, input, { signal })`, or `runCall(voidTarget, undefined, { signal })`.
-`RunCallOptions` contains only the optional `signal`; a pre-aborted signal rejects before the body runs.
+<a id="hello-ui"></a>
+[See Hello UI](../runtime/docs/reference/react.md#react-hello-ui).
 
-`run`, `runCall` and nested `invoke` use the same no-input rule (D273): `void` and `undefined` allow omission;
-other inputs, including `T | undefined`, require an argument. `never` cannot be invoked without input.
-Generic helpers may forward the target and its explicit input without losing their types.
+<a id="selecting-data-and-commands"></a>
+[See Selecting data and commands](../runtime/docs/reference/react.md).
 
-## Word map and entries
+<a id="application-host"></a>
+[See Application host](../runtime/docs/reference/react.md).
 
-| Entry                        | What it holds                                                                                                                                                                                                                                                                                                                         |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@opetope/react`             | `useModel`, `useCommand`, `useCommands`, `useReadable`, `useSelector`, `useResource`, `requiresModels`, `defineSlot`, `defineSwitchSlot`, `Slot`, `ContributionError`; types `SlotTarget`, `SwitchSlotTarget`, `SlotContribution`, `CommandHook`, `CommandOutcome`, `ResourceHook`, `PaginatedResourceHook`, `ResourcePaginationHook` |
-| `@opetope/react/integration` | `FeatureBoundary`, `ContributionBoundary`, `useFeature`, `useFeatureRetry`, `FeatureBoundaryError` for the integration layer; types `FeatureBoundaryProps`, `ContributionBoundaryProps`, `ContributionErrorContent`, `ContributionFailure`, `FeatureDemandSource`, `FeatureDemandState`, `FeatureDemandResult`, `FeatureDemandLease`  |
-| `@opetope/react/testing`     | `renderSlot`, `command`, `createScenario`, `ScenarioTimeoutError` and fixture/scenario types, plus everything `@opetope/runtime/testing` and `@opetope/core/testing` publish; tests only                                                                                                                                              |
+<a id="feature-demand-boundary"></a>
+[See Feature demand boundary](../runtime/docs/reference/react.md).
 
-`Call<Input, Output>` is imported from `@opetope/core`; UI `CommandOutcome<Output>` is imported from `@opetope/react`. The former `Command` synonym and the `CommandOutcome` re-export from `@opetope/react/integration` are removed (D270).
+<a id="contributions"></a>
+[See Contributions](../runtime/docs/reference/react.md).
 
-`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.
+<a id="scenario-tests-and-physical-activity"></a>
+[See Scenario tests and physical activity](../runtime/docs/reference/react.md).
 
-## Laws
+<a id="testing"></a>
+[See Testing](../runtime/docs/reference/react.md).
 
-- `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 does not move `outcome`, 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 `outcome` (D138, D292);
-- a contribution that fails to render or to commit is contained by its own mount and reported to its feature;
-- `useSelector` reads its `equals` where the selected value is known, so a named non-generic comparator compiles
-  beside a selection whose parameter is inferred, as it does in Core (D348);
-- `useSelector` keeps the selected reference when something else changed; its identity case is `useReadable` and its
-  model case is a `useModel` selection, so it is proven by the memory gate and the packaged consumer rather than by a
-  specification example, and it is a candidate to leave this entry until a second application is measured (D301);
-- closing and unmounting synchronously fence new calls and release the references of the frame.
+<a id="word-map-and-entries"></a>
+[See Word map and entries](../runtime/docs/reference/react.md).
 
-## Compatibility contract
+<a id="laws"></a>
+[See Laws](../runtime/docs/reference/react.md).
 
-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.
+<a id="compatibility-contract"></a>
+[See Compatibility contract](../runtime/docs/reference/react.md).

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

@@ -1,4 +1,4 @@
-import type { CallInputArgs, CallRunOptions } from '@opetope/core/internal';
+import type { CommandInputArgs, CallRunOptions } from '@opetope/core/internal';
 import type { CommandOutcome } from './command.js';
 type CommandRunOptions<Output> = Readonly<{
     onFailure?: (error: unknown) => PromiseLike<void> | void;
@@ -7,15 +7,15 @@ type CommandRunOptions<Output> = Readonly<{
 }>;
 type CommandRun<Input, Output> = {
     (input: Input, options?: CommandRunOptions<Output>): Promise<CommandOutcome<Output>>;
-    (...args: [...CallInputArgs<Input>, options?: CommandRunOptions<Output>]): Promise<CommandOutcome<Output>>;
+    (...args: [...CommandInputArgs<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`, `dedupe` — decides what happens to it. What stays
+ * D203: the consumer keeps a status, not a schedule. Every `run` reaches the command, and what the command was
+ * declared with — `concurrency`, `memoize`, `dedupe` — 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> {

package/dist/command-hook.d.ts

@@ -1,10 +1,10 @@
-import type { Call } from '@opetope/core';
+import type { Command } from '@opetope/core';
 import type { CommandOutcome } from './command.js';
 import { CommandHookController } from './command-hook-controller.js';
 import type { CommandRun } from './command-hook-controller.js';
 /** D292: a cancellation is not an answer of the product, so it never settles into the outcome this hook shows. */
 type SettledOutcome<Output> = Exclude<CommandOutcome<Output>, {
-    readonly status: 'cancelled';
+    readonly kind: 'cancelled';
 }>;
 interface CommandHookStatus<Output> {
     readonly inFlight: boolean;
@@ -19,6 +19,6 @@ type CommandHook<Input, Output> = CommandHookStatus<Output> & {
  * it, and the synchronisation of a slot that was already busy when this mount arrived.
  */
 declare function useCommandStatus<Input, Output>(currentSlot: CommandHookController<Input, Output>): CommandHook<Input, Output>;
-declare function useCommand<Input, Output>(command: Call<Input, Output>): CommandHook<Input, Output>;
+declare function useCommand<Input, Output>(command: Command<Input, Output>): CommandHook<Input, Output>;
 export { useCommand, useCommandStatus };
 export type { CommandHook };

package/dist/command.d.ts

@@ -1,21 +1,21 @@
-import type { Call } from '@opetope/core';
-type CommandBinding<Input, Output> = Call<Input, Output>;
+import type { Command } from '@opetope/core';
+type CommandBinding<Input, Output> = Command<Input, Output>;
 type CommandOutcome<Output> = {
     readonly error: unknown;
-    readonly status: 'failed';
+    readonly kind: 'failed';
 } | {
     readonly reason: unknown;
-    readonly status: 'cancelled';
+    readonly kind: 'cancelled';
 } | {
-    readonly status: 'ok';
+    readonly kind: 'ok';
     readonly value: Output;
 };
 type AnyCommandBinding = CommandBinding<never, unknown>;
 type CommandBindingDefinition<Input, Output> = {
-    readonly target: Call<Input, Output>;
+    readonly target: Command<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 bindCommand<Input, Output>(target: Command<Input, Output>): CommandBinding<Input, Output>;
+declare function getCommandBindingDefinition<Input, Output>(binding: Command<Input, Output>): CommandBindingDefinition<Input, Output>;
 declare function isCommandBinding(value: unknown): value is AnyCommandBinding;
 export { bindCommand, getCommandBindingDefinition, isCommandBinding };
 export type { CommandOutcome };

package/dist/contribution-frame-CCKnOxZR.js

@@ -0,0 +1,2 @@
+import{jsx as m}from"react/jsx-runtime";import{useContext as T,createContext as V,useCallback as S,useRef as O,useMemo as p,useSyncExternalStore as k,useEffect as D,useInsertionEffect as A,useLayoutEffect as w,memo as N,useState as W}from"react";import{reportDetachedError as C,compatibleAbortReason as K,isCallTarget as _,isModel as G,isReadable as j,createLifetimeController as H,createCallController as J,getContributionOwner as Q,createState as U,createAggregateError as X}from"@opetope/core/internal";import{isResourceValue as Y,reportRuntimeFailure as Z,requireContributionModelPlans as ee,openContributionModels as te}from"@opetope/runtime/internal";import{C as u,u as ne,b as re}from"./contribution-isolation-Bzfbt4iM.js";import{CommandError as ie}from"@opetope/core";const x=V(void 0);function oe(){const t=T(x);if(t===void 0)throw new u("missing","Opetope hook was called outside a contribution mount.");return t}function y(t){return Y(t)}function se(t,e){return new Promise((n,r)=>{const i=()=>{r(new ie("cancelled","Resource operation wait was cancelled.",K(e)))};if(e.aborted){i();return}e.addEventListener("abort",i,{once:!0}),t.then(o=>{e.removeEventListener("abort",i),n(o)},o=>{e.removeEventListener("abort",i),r(o)})})}function ae(t,e){var r;const n=(r=e==null?void 0:e.onSuccess)==null?void 0:r.call(e,t);return n!==void 0&&Promise.resolve(n).catch(C),t}function v(t){return{run:(e,n)=>{let r;try{r=Promise.resolve(t())}catch(o){return Promise.reject(o)}const i=n==null?void 0:n.signal;return(i===void 0?r:se(r,i)).then(o=>ae(o,n))}}}const ce=Object.freeze({kind:"skipped",reason:"resource-not-ready"});function de(t){const e=t.pagination;if(!(typeof e!="object"||e===null))return e}function E(t){return{loadNext:v(()=>{const e=t.pagination;return e===void 0?Promise.resolve(ce):e.loadNext()}),refresh:v(()=>t.refresh()),reset:v(()=>t.reset()),retry:v(()=>t.retry())}}function ue(t,e){const n=e.get(t);if(n!==void 0)return n;const r=E(t);return e.set(t,r),r}const le=t=>t;function F(t,e,n){const r=e,i=(n==null?void 0:n.equals)??Object.is,o=S(d=>t.subscribe(d),[t]),c=O(void 0);let s=c.current;s===void 0&&(s={hasValue:!1,value:void 0},c.current=s);const a=p(()=>{let d=!1,h,f;return()=>{const b=t.getSnapshot();if(d&&Object.is(h,b))return f;const g=r(b);if(!d){let R=g;return s.hasValue&&i(s.value,g)&&(R=s.value),d=!0,h=b,f=R,f}return i(f,g)?(h=b,f):(h=b,f=g,f)}},[s,i,t,r]),l=k(o,a,a);return D(()=>{s.hasValue=!0,s.value=l},[s,l]),l}function z(t){return F(t,le)}const M=new WeakMap;function I(t){if(arguments.length>1)throw new u("binding-invalid","Command follows the target it binds; binding options are forbidden.");if(!_(t))throw new u("binding-invalid","Command target is not authentic.");return M.set(t,{target:t}),t}function fe(t){const e=M.get(t);if(e===void 0)throw new u("binding-invalid","Command binding is not authentic.");return e}function $(t){return typeof t=="object"&&t!==null&&M.has(t)}const he=Symbol("opetope.model-binding"),me=Symbol("opetope.model-binding-identity"),be=Object.freeze({}),L=new WeakMap;function pe(t,e,n){if(typeof n!="string")throw new u("binding-invalid",`Model ${t.id} accepts only string fields.`);const r=Object.getOwnPropertyDescriptor(e,n);if((r==null?void 0:r.enumerable)!==!0||!("value"in r))throw new u("binding-invalid",`Model ${t.id}.${n} requires an enumerable data binding.`);return r.value}function ge(t,e){const n=[],r=Reflect.ownKeys(e);if(r.length===0)throw new u("binding-invalid",`Model ${t.id} requires at least one field.`);for(const i of r){const o=pe(t,e,i);if(!(j(o)||y(o)||typeof o=="function")){if(!$(o))throw new u("binding-invalid",`Model ${t.id}.${String(i)} requires a Readable, a Resource or a bound command.`);n.push(o)}}return Object.freeze(n)}function q(t,e){if(!G(t))throw new u("binding-invalid","Model declaration is not authentic.");if(typeof e!="object"||e===null)throw new u("binding-invalid",`Model ${t.id} requires a record binding.`);const n=ge(t,e),r=Object.freeze({[he]:be,[me]:!0});return L.set(r,{commands:n,declaration:t,model:e}),r}function we(t){const e=L.get(t);if(e===void 0)throw new u("binding-invalid","Model binding is not authentic.");return e}let Ce=0;function ve(t){const e=new Map,n=[],r=new Set;for(const i of t){const o=we(i);if(e.has(o.declaration))throw new u("duplicate",`Model ${o.declaration.id} is bound twice in one mount.`);e.set(o.declaration,o.model);for(const c of o.commands)r.has(c)||(r.add(c),n.push(c))}return{commands:Object.freeze(n),frame:{commandRecords:new Map,models:e}}}class ye{frame;authority;boundCommands;closeTicket=0;isActive;lifetime;onClose;released=!1;rendererAttached=!1;renderListeners=new Set;state="detached";constructor(e,n){const r=++Ce;this.lifetime=H({id:`contribution.${String(r)}`}),this.isActive=n==null?void 0:n.isActive,this.onClose=n==null?void 0:n.onClose;const{commands:i,frame:o}=ve(e);this.frame=o,this.boundCommands=i,this.buildCommandRecords(r)}attach(){if(this.state==="closing")return this.closeTicket+=1,this.state="active",this.rendererAttached=!0,!0;if(this.state==="closed")return!1;if(this.state==="active")throw new u("duplicate","One contribution mount cannot mount twice.");const e=this.createAuthority(this.lifetime.open());try{for(const n of this.frame.commandRecords.values())n.controller.activate()}catch(n){throw this.authority=e,this.state="active",this.close(),n}return this.authority=e,this.rendererAttached=!0,this.state="active",!0}close(){if(this.state==="closed")return;this.state="closed",this.closeTicket+=1,this.lifetime.close(),this.authority=void 0;for(const n of this.frame.commandRecords.values())n.controller.close();const e=this.onClose;this.onClose=void 0,e==null||e(),this.publishRenderable(),this.rendererAttached||this.releaseFrame()}detach(){if(!this.rendererAttached)return;if(this.rendererAttached=!1,this.state==="closed"){this.releaseFrame();return}if(this.state!=="active")return;this.state="closing";const e=++this.closeTicket;queueMicrotask(()=>{this.state==="closing"&&e===this.closeTicket&&this.close()})}diagnostics(){const e=[...this.frame.commandRecords.values()].map(n=>n.controller.diagnostics());return Object.freeze({active:this.state==="active",calls:Object.freeze(e),commandRecords:this.frame.commandRecords.size,models:this.frame.models.size})}getRenderableSnapshot=()=>this.state!=="closed"&&(this.isActive===void 0||this.isActive());releaseClosedFrame(){this.state==="closed"&&this.releaseFrame()}subscribeRenderable=e=>{if(this.state==="closed")return()=>{};const n={listener:e};this.renderListeners.add(n);let r=!0;return()=>{r&&(r=!1,this.renderListeners.delete(n))}};buildCommandRecords(e){let n=0;for(const r of this.boundCommands){fe(r);const i=J(r,{captureAuthority:this.captureAuthority,id:`contributionCommand.${String(e)}.${String(++n)}`,scheduling:{policy:"parallel"}});this.frame.commandRecords.set(r,{controller:i,invoker:Object.freeze({run:i.run})})}}captureAuthority=()=>{const e=this.authority;if(this.state!=="active"||e===void 0)throw new u("inactive","Contribution mount is not active.");return e.assertCurrent(),e};createAuthority(e){return Object.freeze({assertCurrent:()=>{if(this.state!=="active")throw new u("inactive","Contribution mount is not active.");e.assertCurrent()},isCurrent:()=>this.state==="active"&&e.isCurrent()})}publishRenderable(){for(const{listener:e}of[...this.renderListeners])try{e()}catch(n){C(n)}}releaseFrame(){this.released||(this.released=!0,this.frame.commandRecords.clear(),this.frame.models.clear(),this.boundCommands=[],this.renderListeners.clear())}}function Me({children:t,mount:e}){const n=k(e.subscribeRenderable,e.getRenderableSnapshot,e.getRenderableSnapshot);return A(()=>{if(e.attach())return()=>e.detach()},[e]),w(()=>{n||e.releaseClosedFrame()},[e,n]),n?m(x,{value:e.frame,children:t}):null}function B(t){const e=t.bundle;t.bundle=void 0,e==null||e.frame.close()}function Re(t,e){if(typeof e!="object"||e===null)return q(t,e);const n=i=>j(i)||y(i)||typeof i=="function"||$(i),r=Object.entries(e).map(([i,o])=>[i,n(o)?o:I(o)]);return q(t,Object.fromEntries(r))}function Se(t){return Q(t)}const Oe={models:[]};function P(t,e){try{t()}catch(n){throw X([e,n],"Contribution mount setup and cleanup failed.",{cause:e})}throw e}function ke(t,e,n,r){const i=U(e),{models:o,reporter:c}=r??Oe;try{const s=ee(t.models),a=s.length===0?void 0:te(s,i,c);return{bundle:a,models:[...o,...(a==null?void 0:a.models)??[],...n],props:i}}catch(s){return P(i.close,s)}}function Ae(t,e,n,r){const{bundle:i,models:o,props:c}=ke(t,e,n,r);let s=!1;const a=()=>{if(!s){s=!0;try{i==null||i.close().catch(C)}finally{c.close()}}};try{return{frame:new ye(o.map(([d,h])=>Re(d,h)),{isActive:()=>!s,onClose:a}),isOpen:()=>!s,props:c}}catch(l){return P(a,l)}}function je(t,e){return m(t,{...e})}function xe({bundle:t,contribution:e}){const n=z(t.props),r=p(()=>e.props===void 0?n:e.props(n),[n,e]);return m(Me,{mount:t.frame,children:je(e.Component,r)})}function Ee({authority:t,contribution:e,fixtures:n,slotProps:r}){const i=p(()=>({authority:t,bundle:void 0,contribution:e,fixtures:n,retired:!1}),[t,e,n]),[o,c]=W(void 0),s=(o==null?void 0:o.owner)===i?o.bundle:void 0,a=O(r);return w(()=>{a.current=r}),A(()=>()=>{i.retired=!0,queueMicrotask(()=>{try{B(i)}catch(l){C(l)}})},[i]),w(()=>{const l=i.bundle??(i.bundle=Ae(i.contribution,a.current,i.fixtures??[],i.authority));return c(d=>(d==null?void 0:d.owner)===i?d:{bundle:l,owner:i}),()=>{i.retired&&B(i)}},[i]),w(()=>{(s==null?void 0:s.isOpen())===!0&&s.props.set(r)},[s,r]),s===void 0?null:m(xe,{bundle:s,contribution:e})}function Fe(t){const{authority:e,contribution:n,contributionId:r,fixtures:i,targetId:o}=t,c=ne(),s=p(()=>({authority:e,contribution:n,fixtures:i}),[e,n,i]),a=e==null?void 0:e.feature,l=p(()=>({contribution:r,feature:a,target:o}),[r,a,o]),d=e==null?void 0:e.reporter,h=S(f=>Z(f,d),[d]);return m(re,{content:c,identity:s,report:h,source:l,children:m(Ee,{...t})})}const ze=N(Fe);export{ze as M,z as a,Se as b,E as c,F as d,I as e,y as i,de as p,ue as r,oe as u};
+//# sourceMappingURL=contribution-frame-CCKnOxZR.js.map