@opetope/react 0.10.1 → 0.12.0

package/README.md

@@ -19,12 +19,12 @@ No GitHub access is needed to read those installed guides.
 
 ```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 +39,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>
   );
 });
@@ -57,10 +57,10 @@ 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`.
+its discriminant — `outcome?.kind === '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
+keeps the React event out of the Command 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).
@@ -70,39 +70,25 @@ changes as `inFlight` or `outcome` changes, so an effect or a memo depends on `r
 `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.
+The hook schedules nothing. Every `run` reaches the command, and the order the command was declared with decides
+what happens to it (D203). For an absolute value setter the model declares `concurrency: 'latest'` in
+`context.command`, and the newest input then replaces the waiting one there (D185, D387). What the consumer keeps
+is its own: an already-aborted input signal is refused as `cancelled` without reaching the command, 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.
+on `context.command`. Sharing keeps the first input and each caller's independent cancellation; neither form may
+be combined with `latest` (D277). These are Command options, not hook options.
 
-For several commands use an object selection (D174):
+For several commands a component writes `useCommand` per command, or one `useModel` selection, which already
+answers ready hooks. `useCommands` is gone: a record over the one `CommandHook` was sugar that saved hook calls,
+not a second mechanism, and the set that is really wanted is a selection in the model, where `ctx.select` gives it
+an owner and a lifetime (D388).
 
-```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.
+Two aliases of one Command have independent local statuses, just like two `useCommand` consumers; they use the same
+Command concurrency and mount command record (D197, D203). A selection introduces no shared busy state, queue or
+transaction; controls that overwrite one value still need one semantic command.
 
 ## Selecting data and commands
 
@@ -110,10 +96,22 @@ need one semantic command. Only own enumerable properties are selected, includin
 
 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`.
+`read(source)` returns its snapshot; `read(source, project)` returns a projection. Authentic Commands selected as
+record fields become the same `CommandHook` as `useCommand`, including independent alias statuses and stable `.run`.
 A single selected command needs no nested hooks:
 
+<!--example
+import type { Command } from '@opetope/core';
+import { defineModel } from '@opetope/core';
+import { useModel } from '@opetope/react';
+
+const AuthModel = defineModel<{ readonly logout: Command<void, void> }>('example.auth.model');
+
+const LogOutButton = () => {
+/* … */
+};
+-->
+
 ```tsx
 const { logout } = useModel(AuthModel, auth => ({ logout: auth.logout }));
 return (
@@ -136,13 +134,26 @@ values — that field answers a `ResourceHook`, and one lease per Resource ident
 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.
+There is no additional Command 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:
 
+<!--example
+import { defineSlot, Slot } from '@opetope/react';
+
+const exampleFooterSlot = defineSlot('example.footer');
+const exampleSettingsSlot = defineSlot('example.settings');
+
+const ExampleShell = () => (
+  <>
+/* … */
+  </>
+);
+-->
+
 ```tsx
 <Slot target={exampleFooterSlot} />
 <Slot target={exampleSettingsSlot} />
@@ -152,6 +163,26 @@ The application owns feature lifetimes; each feature's UI mounts through its con
 
 ## Feature demand boundary
 
+<!--example
+import type { ReactNode } from 'react';
+import type { Resource } from '@opetope/core';
+import { defineSlot } from '@opetope/react';
+import type { FeatureDemandSource } from '@opetope/react/integration';
+
+type Tasks = Readonly<{ id: string }>;
+type ConfirmActionProps = Readonly<{ itemId: string; onConfirmed: () => void }>;
+
+declare const host: FeatureDemandSource<Readonly<{ exports: Readonly<{ tasks: Resource<Tasks, 'none'> }> }>>;
+declare const itemId: string;
+declare const onConfirmed: () => void;
+declare const children: ReactNode;
+declare const Spinner: () => null;
+declare const Failure: (props: Readonly<{ error: unknown; onRetry: () => void }>) => null;
+declare const TasksResourceLease: (props: Readonly<{ children: ReactNode; resource: Resource<Tasks, 'none'> }>) => null;
+
+const confirmActionContentSlot = defineSlot<ConfirmActionProps>('example.confirmAction.content');
+-->
+
 ```tsx
 import { Slot } from '@opetope/react';
 import { FeatureBoundary, useFeatureRetry } from '@opetope/react/integration';
@@ -211,27 +242,30 @@ frame of the instance that gave the contribution. The order and the stable key c
 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
+`useResource(resource)` answers `{ pagination, refresh, reset, 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 answers the same hook and takes the same lease, so a model declares no `Command<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
+`refresh.run()`, `retry.run()` and `reset.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 answers the last state it saw — what `useReadable` does with a source
-its owner closed — and a selection answers a closed record instead of throwing mid-render, so the tree unmounts and
-releases its lease rather than breaking the render (D359).
+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
@@ -248,6 +282,14 @@ Every mount is an error boundary of its own contribution (D256). A render or com
 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:
 
+<!--example
+import { defineSlot, Slot } from '@opetope/react';
+
+declare const FailedContribution: (props: Readonly<{ error: unknown; onRetry: () => void }>) => null;
+
+const applicationSurface = defineSlot('example.surface');
+-->
+
 ```tsx
 import { ContributionBoundary } from '@opetope/react/integration';
 
@@ -273,7 +315,7 @@ dependency. `scenario.mount(target, { props })` uses the published Slot contribu
 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).
+computed through `source`/`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
@@ -292,17 +334,18 @@ a scoped zero-count assertion, without proving absence of arbitrary host, UI or
 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/4`, with optional
+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
+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.
+`closed: true` says that the close of the application finished, whether its physical drain succeeded or refused, and
+the snapshot of a closed application names no feature and no Resource (D427). 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
@@ -315,14 +358,14 @@ observation disabled. Graph frames remain bounded by the existing ring capacity.
 (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);
+- `command(run)` produces an authentic `Command` for a model fixture, plus the contribution binding a mount reads;
+- `runCommand(target, input?, options?)` executes an existing authentic `Command` 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`
+`command` are all that needs React here. The Command 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.
 
@@ -331,21 +374,21 @@ application as contributions (D85). It is not a test spelling of `<Slot>` — it
 `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:
+A test that previously mounted `useCommand` only to invoke a Command can use `runCommand` directly. The result is the
+Command'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 type { Command, ModelCommandContext } from '@opetope/core';
 import { defineFeature, openFeature } from '@opetope/runtime';
-import { runCall } from '@opetope/react/testing';
+import { runCommand } from '@opetope/react/testing';
 
-const Arithmetic = defineModel<{ readonly double: Call<number, number> }>('example.testing.model');
+const Arithmetic = defineModel<{ readonly double: Command<number, number> }>('example.testing.model');
 const arithmetic = defineFeature('example.testing.arithmetic', {
   own: ({ model }) => ({
     arithmetic: model(Arithmetic, context => ({
-      double: context.call((input: number) => input * 2),
+      double: context.command(({ input }: ModelCommandContext<number>) => input * 2),
     })),
   }),
   exports: ({ own }) => ({ double: own.arithmetic.double }),
@@ -353,35 +396,35 @@ const arithmetic = defineFeature('example.testing.arithmetic', {
 const instance = openFeature(arithmetic, { imports: {}, reporter: () => undefined });
 try {
   const ready = await instance.ready;
-  const result = await runCall(ready.exports.double, 3);
+  const result = await runCommand(ready.exports.double, 3);
   assert.equal(result, 6);
 } finally {
   await instance.close();
 }
 ```
 
-`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
+`runCommand` returns `Promise<Output>` and preserves the Command's original errors and cancellation rejections. It adds no
+UI status or outcome wrapper, scheduling policy, model creation or cleanup lifetime. The existing Command 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 void Command can use `runCommand(target)`. Options always occupy the third argument:
+`runCommand(target, input, { signal })`, or `runCommand(voidTarget, undefined, { signal })`.
+`RunCommandOptions` contains only the optional `signal`; a pre-aborted signal rejects before the body runs.
 
-`run`, `runCall` and nested `invoke` use the same no-input rule (D273): `void` and `undefined` allow omission;
+`run`, `runCommand` 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.
 
 ## 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`, `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                                                                                                                                              |
+| Entry                        | What it holds                                                                                                                                                                                                                                                                                                                        |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@opetope/react`             | `useModel`, `useCommand`, `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                                                                                                                                             |
 
-`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).
+`Command<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).
 
-`Model` is a typed key for a record of `Readable`, `Call` and readable factories that UI components consume.
+`Model` is a typed key for a record of `Readable`, `Command` 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.
 
@@ -391,7 +434,7 @@ The constructors of the integration entry are not re-exported from the safe entr
 - 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`
+- the `cancelled` outcome does not move `outcome`, and it is only the `CommandError` 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;