@xmachines/docs 6.0.0 → 7.0.0

package/api/@xmachines/play-dom/interfaces/ValidationRegistry.md

@@ -8,14 +8,17 @@ Registry of validated fields for one rendered tree.
 
 ## Properties
 
-| Property                                                | Modifier   | Type                                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                            | Defined in |
-| ------------------------------------------------------- | ---------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| <a id="property-clear"></a> `clear`                     | `public`   | (`path`) => `void`                                                      | Forget a field's recorded state; the registration itself survives.                                                                                                                                                                                                                                                                                                                                                     | -          |
-| <a id="property-customfunctions"></a> `customFunctions` | `readonly` | `Record`\<`string`, `ValidationFunction`\>                              | Custom validation functions available to every check.                                                                                                                                                                                                                                                                                                                                                                  | -          |
-| <a id="property-fieldstates"></a> `fieldStates`         | `readonly` | `Record`\<`string`, [`FieldValidationState`](FieldValidationState.md)\> | Validation state by field state path.                                                                                                                                                                                                                                                                                                                                                                                  | -          |
-| <a id="property-registerfield"></a> `registerField`     | `public`   | (`path`, `config`) => `void`                                            | Register (or update) a field's validation config. Called by component implementations during render, normally via `ctx.validation`. Registrations are reference-counted per path: two elements bound to the same state path each hold one, so one of them going away does not un-validate the other.                                                                                                                   | -          |
-| <a id="property-releasefield"></a> `releaseField`       | `public`   | (`path`) => `void`                                                      | Drop one reference to a field's registration, keeping its recorded state. The registration itself goes away once the last reference is released. This is what the render context's per-element cleanup calls: an element instance releases its registrations when it unmounts or before it re-renders, and `fieldStates` survives — matching the framework ValidationProvider, whose field states outlive a re-render. | -          |
-| <a id="property-touch"></a> `touch`                     | `public`   | (`path`) => `void`                                                      | Mark a field as interacted with, without validating it.                                                                                                                                                                                                                                                                                                                                                                | -          |
-| <a id="property-unregisterfield"></a> `unregisterField` | `public`   | (`path`) => `void`                                                      | Drop a field's registration entirely, references and recorded state.                                                                                                                                                                                                                                                                                                                                                   | -          |
-| <a id="property-validate"></a> `validate`               | `public`   | (`path`, `config?`) => `ValidationResult`                               | Validate one field against the live store snapshot and record the result. Uses the field's registered config unless one is passed explicitly.                                                                                                                                                                                                                                                                          | -          |
-| <a id="property-validateall"></a> `validateAll`         | `public`   | () => `boolean`                                                         | Validate every registered field. Returns true when all are valid.                                                                                                                                                                                                                                                                                                                                                      | -          |
+| Property                                                | Modifier   | Type                                                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Defined in |
+| ------------------------------------------------------- | ---------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| <a id="property-clear"></a> `clear`                     | `public`   | (`path`) => `void`                                                 | Forget a field's recorded state; the registration itself survives.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | -          |
+| <a id="property-customfunctions"></a> `customFunctions` | `readonly` | `Record`\<`string`, `ValidationFunction`\>                         | Custom validation functions available to every check.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -          |
+| <a id="property-dropreleased"></a> `dropReleased?`      | `public`   | () => `void`                                                       | End a pass. The registry forgets the state of each field whose last registration went away and that did not register again. It also forgets the state of a field that only new owners hold now: an element that goes and another element that registers the path in the same pass start the field fresh, as in the framework renderers, whatever the order of the two. What a new owner wrote in the pass stays, as if the field started fresh at the change: a `touch` of the new owner gives no result of the old one. A write of the old owner in the pass goes. An owner that registers again in place keeps the state. The fresh start comes when the pass ends. A component of the new element that reads `fieldStates` while it renders in that pass still reads the state of the old element. The incremental renderer then renders it again (see `onFreshPaths`), as React renders it again after the unmount of the old one. A caller that does not mark its passes with `startPass` calls it when a pass ends, for example a host that renders with `renderSpec` alone on a registry of its own. The incremental renderer and a host that uses `startPass` end a pass with the function that `startPass` returns, and not with this. The registry counts the passes by these calls, or by `startPass`: an owner that came to the path in an earlier pass is an owner from before the pass. Without the calls, no owner is from before, and the state of a field stays with its path.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | -          |
+| <a id="property-fieldstates"></a> `fieldStates`         | `readonly` | `Readonly`\<`Record`\<`string`, `ReadonlyFieldValidationState`\>\> | Validation state by field state path. The registry gives the same object until a state changes, as the state of react does. The object and each state in it are shared by every reader, so they are read-only at each level: the registry of this package freezes the object, each state, and the result of each state with its errors and its checks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -          |
+| <a id="property-onfreshpaths"></a> `onFreshPaths?`      | `public`   | (`listener`) => () => `void`                                       | Call `listener` with the paths whose state changed: a pass that started a field fresh for a new element that took over the path, or a write of the state, such as a `touch` or a `validateAll`. Each renderer of the registry renders the elements that hold such a path again, so they show the state of now, as React renders a component again when the state of its provider changes. A write in a pass reaches the listeners when the pass ends, and a write between two passes at once. The writes of one `validateAll` reach them together. The registry calls the listeners after the outermost pass ends, and it holds each one weakly: the caller keeps its listener while it needs the calls. An error of a listener goes to `reportError`, and the other listeners still run. Returns the function that stops the calls.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | -          |
+| <a id="property-registerfield"></a> `registerField`     | `public`   | (`path`, `config`, `owner?`) => `void`                             | Register (or update) a field's validation config. Called by component implementations during render, normally via `ctx.validation`. Registrations are reference-counted per path: two elements bound to the same state path each hold one, so one of them going away does not un-validate the other. `owner` names the element instance that registers. For a registration through `ctx.validation`, the renderer gives the element, its type, its repeat rows, the keys and the types of the elements above it, and the named slot that holds it. Registrations that name no owner count as one owner. See [ValidationRegistry.dropReleased](#property-dropreleased) for what it changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | -          |
+| <a id="property-releasefield"></a> `releaseField`       | `public`   | (`path`, `owner?`) => `void`                                       | Drop one reference to a field's registration. The registration goes away once the last reference is released, and [ValidationRegistry.dropReleased](#property-dropreleased) forgets its state, unless the field registers again first. Until then `fieldStates` keeps the state, so an element that renders before the field in the same pass still reads it. This is what the render context's per-element cleanup calls: an element instance releases its registrations when it unmounts or before it re-renders. An element that renders again in place registers again in the same pass, so its state survives — matching the framework ValidationProvider, whose field states outlive a re-render and go at the last unregister. `owner` is the owner that [ValidationRegistry.registerField](#property-registerfield) got.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | -          |
+| <a id="property-startpass"></a> `startPass?`            | `public`   | (`options?`) => () => `void`                                       | Start a pass, and return the function that ends it. The incremental renderer calls it before each pass, and a host that renders with `renderSpec` before its render. A pass of a renderer that starts inside a pass ends with the outer one. A pass of the host that starts inside a pass commits the passes that run when it ends, as react commits a nested `flushSync` when it returns, and a call of the host after it sees that commit. An owner that comes to a path between two passes, for example through a late read of the children of a component, then comes before the next pass. A caller that does not call it ends and counts each pass with `dropReleased` alone, and inside a pass `dropReleased` does nothing. All the callers of one registry follow the same rule: after the first `startPass`, `dropReleased` does nothing, and the registry warns one time. An outermost pass that starts before the join of the outermost pass before it ends joins that pass, as react joins the updates of one commit. The `batch` of the pass before sets how long its join lasts (see [PassOptions](PassOptions.md)): to the next microtask for a store write, and to the end of the task, also after an `await`, for a new spec. A write of a field state, a `clear`, or a field that registers between the two passes ends the join. A write of a field state or a `clear` before the commit point of a store write does not: it is part of that commit (see the pass of a store write below). The renderers of one registry that react to one write of the store, or that a host hands new specs in one task, then run one pass. A field that moves from one renderer to the other starts fresh, whatever the order of the two. A pass that a handler of a pass queued is a new pass, as an update that a commit schedules is a new commit: its caller gives `join: false`. The incremental renderer marks the pass of a store write and the pass of a new spec. React commits a store write and a new spec after the handler that gives them, so the registry holds the effects of such a pass on the fields, a release, a new config and a fresh start, until its commit point: the next microtask, the next pass that does not join it, the bindings of a `watch`, or a field that registers between two passes. The commit point of a store write ends the join, so a pass after it starts a new commit. The commit point of a new spec keeps the join to the end of the task (see [PassOptions](PassOptions.md)). The renderer shows the store writes of the task at the commit point, in one render, as react renders the writes of one handler in one render. The commit point then does the work of the commit, it runs the effects that the components of the commit gave `ctx.effect` and the checks of the watches, and it renders the holders of the commit again, before its microtask ends. React ends the commit of a synchronous update in its microtask in the same way: it runs the effects of the commit before the renders that its layout effects start. The checks of the watches run after the effects, as react runs the effect of a child before the watch of its parent. The watches of one change see one commit. Their writes and the writes of those effects make one commit after them, and the commit point shows its store writes before its microtask ends, as react renders a store write of an effect at the end of the flush of the effects. A watch compares the store of its commit, from before the effects: when an effect writes a watched path, the watch sees the change at the commit point of that write. A `touch`, a `validate`, a `clear` or a `validateAll` before the commit point sees the fields of before the write, as in react. A write of a field state between two passes renders the holders of its path, and the registry holds the effects of that render in the same way. The incremental renderer renders them at the commit point when a store write of it waits, in the one render of its store writes, as react renders them after the handler. A render of a holder for its new config, which the end of such a pass starts, waits with it. The end of a pass of the host shows the store writes that wait, as `flushSync` of react renders the updates that wait, and it commits them with the passes that it joins. A call of the host inside such a pass sees the fields of the last commit, as a call inside the callback of `flushSync` of react does. This also holds after a store write before the pass: the end of the pass shows and commits that write too. The end of a pass of the host then runs the effects of its commit, as `flushSync` of react does: the effects that the components of the incremental renderer gave `ctx.effect`, also in a render before the pass, and then the checks of the watches. It commits their writes, and it runs the effects of those writes in the same way. The end of an outermost pass of the host ends its join, so a later pass starts a new commit. | -          |
+| <a id="property-touch"></a> `touch`                     | `public`   | (`path`, `owner?`) => `void`                                       | Mark a field as interacted with, without validating it. `owner` names the element that touches it, as for `registerField`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | -          |
+| <a id="property-unregisterfield"></a> `unregisterField` | `public`   | (`path`) => `void`                                                 | Drop a field's registration entirely, references and recorded state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | -          |
+| <a id="property-validate"></a> `validate`               | `public`   | (`path`, `config?`, `owner?`) => `ReadonlyValidationResult`        | Validate one field against the live store snapshot and record the result. Uses the field's registered config unless one is passed explicitly. `owner` names the element that validates, as for `registerField`. The result is the result of the state of the field, which every reader of `fieldStates` shares, so it is read-only at each level: the registry of this package freezes it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | -          |
+| <a id="property-validateall"></a> `validateAll`         | `public`   | () => `boolean`                                                    | Validate every registered field. Returns true when all are valid. The listeners of `onFreshPaths` hear of the new states one time, when the last field is validated, so no holder renders in the loop.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | -          |

package/api/@xmachines/play-dom/type-aliases/ConfirmHandler.md

@@ -10,16 +10,15 @@ Defined in: `@xmachines/json-render-dom`
 
 Hook consulted before executing an action binding that declares `confirm`.
 
-The DOM renderer is headless, so instead of the framework adapters'
-`pendingConfirmation` state (which a dialog component resolves via
-`confirmAction()` / `cancelAction()`), @xmachines/json-render-dom exposes a single async
-callback: return (or resolve) `true` to execute the action, `false` to
-skip it. The confirmation flow — `window.confirm`, a custom dialog, or a
-test stub — is entirely the host's responsibility.
-
-If no `ConfirmHandler` is configured, confirm-gated actions do NOT execute;
-a `console.warn` is emitted instead. This matches the framework adapters,
-where a pending confirmation that is never resolved never runs the handler.
+With this hook, the host owns the confirmation flow — `window.confirm`, a
+custom dialog, or a test stub: return (or resolve) `true` to execute the
+action, `false` to skip it.
+
+Without it, the renderer works as the framework renderers do: the binding
+waits as the pending confirmation of the tree, which a component reads and
+answers through `ctx.confirmation`, and the default confirm dialog shows it
+(`createConfirmDialog`; turn it off with the `confirmDialog: false`
+option). A cancel runs nothing and throws nothing.
 
 ## Parameters
 

package/api/@xmachines/play-dom/type-aliases/DefineRegistryOptions.md

@@ -16,9 +16,10 @@ fully typed. When the catalog declares actions, `actions` is required; otherwise
 
 ## Type Declaration
 
-| Name          | Type                                               | Description                                                                                                                                                             | Defined in |
-| ------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| `components?` | [`ComponentRegistry`](ComponentRegistry.md)\<`C`\> | Catalog-typed component implementations. If omitted, all elements fall through to the `fallback` renderer (if provided) or return `null` — the container will be empty. | -          |
+| Name             | Type                                               | Description                                                                                                                                                                                                                                  | Defined in |
+| ---------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `components?`    | [`ComponentRegistry`](ComponentRegistry.md)\<`C`\> | Catalog-typed component implementations. If omitted, all elements fall through to the `fallback` renderer (if provided) or return `null` — the container will be empty.                                                                      | -          |
+| `onRenderError?` | [`OnRenderError`](OnRenderError.md)                | The error handler of the registry, as in the framework renderers. `defineRegistry` puts it on the registry as a property that is not enumerable. The `onRenderError` option of `renderSpec` and of the incremental renderer takes its place. | -          |
 
 ## Type Parameters
 

package/api/@xmachines/play-dom/type-aliases/MountFn.md

@@ -6,7 +6,7 @@
 type MountFn = (actor, container, options?) => () => void;
 ```
 
-Defined in: [packages/play-dom/src/create-play-ui.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/src/create-play-ui.ts#L82)
+Defined in: [packages/play-dom/src/create-play-ui.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom/src/create-play-ui.ts#L82)
 
 The mount function that `createPlayUI` returns.
 

package/api/@xmachines/play-dom/type-aliases/OnRenderError.md

@@ -0,0 +1,27 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / OnRenderError
+
+# Type Alias: OnRenderError
+
+```ts
+type OnRenderError = (error, name, info) => void;
+```
+
+Defined in: `@xmachines/json-render-core`
+
+The `onRenderError` handler of a renderer.
+
+The second argument stays as it was: the element type for a failure of an
+element, or the action name for a failed chain. `info` tells them apart. A
+handler with two parameters is still a valid handler.
+
+## Parameters
+
+| Parameter | Type                                                  |
+| --------- | ----------------------------------------------------- |
+| `error`   | `unknown`                                             |
+| `name`    | `string`                                              |
+| `info`    | [`RenderErrorInfo`](../interfaces/RenderErrorInfo.md) |
+
+## Returns
+
+`void`

package/api/@xmachines/play-dom/type-aliases/RenderErrorKind.md

@@ -0,0 +1,21 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / RenderErrorKind
+
+# Type Alias: RenderErrorKind
+
+```ts
+type RenderErrorKind = "element" | "props" | "visible" | "action" | "watch" | "root";
+```
+
+Defined in: `@xmachines/json-render-core`
+
+The place where a failure occurred.
+
+- `element`: the component threw while it rendered, in an effect or a
+  lifecycle hook, or in a callback that it calls in those phases.
+- `props`: a prop expression of an element threw (`$computed`, a directive).
+- `visible`: the `visible` condition of an element threw.
+- `action`: an `on` chain failed: a handler that throws or rejects, a
+  built-in action, a store that refuses a write, or `validateForm`.
+- `watch`: a `watch` chain failed.
+- `root`: the root (its component, props or `visible`) failed, so the
+  renderer shows nothing.

package/api/@xmachines/play-dom-router/README.md

@@ -4,7 +4,7 @@
 
 **Vanilla DOM router (Browser History API) for XMachines Play Architecture.**
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-6.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom-router)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-7.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom-router)
 
 This framework-agnostic router integration keeps the `currentRoute` atom of a Play actor and the `window.history` API of the browser in step. It needs no framework. It implements the same [`RouterBridgeBase`](../play-router/README.md) pattern as every other router adapter in the XMachines ecosystem.
 
@@ -50,7 +50,7 @@ reach [`@xmachines/play-router/xstate`](../play-router/README.md), which holds `
 
 A history that you inject for a test or for SSR is a plain object. `subscribe` returns a plain function:
 
-```typescript
+```typescript fragment
 import type { BrowserHistory } from "@xmachines/play-dom-router";
 
 const history: BrowserHistory = {
@@ -124,6 +124,8 @@ function teardown(): void {
 This function wraps `window.history`, and it gives you a history interface with a subscription. It patches `pushState` and `replaceState`. Therefore the wrapper also detects a navigation from the code, not only a `popstate` event from the BACK or FORWARD button.
 
 ```typescript
+import { createBrowserHistory } from "@xmachines/play-dom-router";
+
 const history = createBrowserHistory({ window });
 
 // Subscribe to URL changes
@@ -164,7 +166,14 @@ The interface accepts `window`, a JSDOM window, or every other object that imple
 This function creates a `VanillaRouter` around a `history` and a `routeTree`. Its setup flow is the same as the setup flow of TanStack Router.
 
 ```typescript
-// routeTree and history from the Quick Start above
+import { createBrowserHistory, createRouter } from "@xmachines/play-dom-router";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // the machine of the Quick Start above
+
+const routeTree = extractMachineRoutes(machine);
+const history = createBrowserHistory({ window });
 const router = createRouter({ routeTree, history });
 // router.history — the BrowserHistory instance
 // router.routeTree — for structure reference
@@ -175,7 +184,14 @@ Or let a scope release it, which also releases the history on an exception. Publ
 
 ```typescript
 import { asDisposable } from "@xmachines/core/utils";
+import { createBrowserHistory, createRouter } from "@xmachines/play-dom-router";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // the machine of the Quick Start above
 
+const routeTree = extractMachineRoutes(machine);
+const history = createBrowserHistory({ window });
 const plain = createRouter({ routeTree, history });
 using router = asDisposable(plain, () => plain.destroy());
 ```
@@ -195,6 +211,17 @@ This function connects a history to a `Routable` actor. It does all the work in
 - Returns a cleanup function that disconnects the bridge.
 
 ```typescript
+import {
+	connectRouter,
+	type RoutableActor,
+	type RouteLookupContract,
+	type VanillaRouter,
+} from "@xmachines/play-dom-router";
+
+declare const actor: RoutableActor;
+declare const router: VanillaRouter;
+declare const routeMap: RouteLookupContract;
+
 const disconnect = connectRouter({
 	actor, // RoutableActor — an actor of the `PlayActor` contract that adds `Routable` satisfies this structurally
 	router, // the router from createRouter(), or any { history }
@@ -229,8 +256,17 @@ The bridge accepts every object that implements this structural interface. A `Ro
 This package re-exports it never: the barrel names no state machine. The function builds a bidirectional `RouteMap` from an XState machine:
 
 ```typescript
+import { createMachine } from "xstate";
 import { createRouteMap } from "@xmachines/play-router/xstate";
-// machine from the Quick Start above (states carry meta.route)
+
+// A machine whose states carry meta.route, as in the Quick Start above
+const machine = createMachine({
+	id: "app",
+	initial: "dashboard",
+	states: {
+		dashboard: { id: "dashboard", meta: { route: "/dashboard" } },
+	},
+});
 const routeMap = createRouteMap(machine);
 routeMap.getStateIdByPath("/dashboard"); // "dashboard"
 routeMap.getPathByStateId("dashboard"); // "/dashboard"
@@ -241,7 +277,7 @@ routeMap.getPathByStateId("dashboard"); // "/dashboard"
 The bridge-first data flow:
 
 1. `connectRouter` creates a `DomRouterBridge`, which extends `RouterBridgeBase`, and calls `bridge.connect()`.
-2. On connect, `RouterBridgeBase` does the first synchronization. If the browser URL is different from the actor route, the bridge sends a `play.route` event. If the actor route is different and the browser is at the initial route of the machine (a restore), the actor wins, and the bridge updates the history.
+2. On connect, `RouterBridgeBase` does the first synchronization. If the browser URL is different from the actor route, the bridge sends a `play.route` event. If the actor route is different and the browser is at the initial URL of the machine, with the same path and the same query (a restore), the actor wins, and the bridge updates the history. A query of the browser at the initial path makes a deep link, and the router wins.
 3. Each actor route change, through the `currentRoute` Atom, calls `history.push(path)`.
 4. Each browser URL change (a `popstate` event, or a patched `pushState` or `replaceState` call) calls `syncActorFromRouter(pathname, search)`, which sends a `play.route` event.
 5. The `isProcessingNavigation` flag in `RouterBridgeBase` stops a circular update.

package/api/@xmachines/play-dom-router/classes/DomRouterBridge.md

@@ -2,7 +2,7 @@
 
 # Class: DomRouterBridge
 
-Defined in: [play-dom-router/src/dom-router-bridge.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/dom-router-bridge.ts#L27)
+Defined in: [play-dom-router/src/dom-router-bridge.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom-router/src/dom-router-bridge.ts#L27)
 
 The DOM router bridge — it puts a BrowserHistory from `createBrowserHistory`
 behind the `RouterBridgeBase` protocol.
@@ -42,7 +42,7 @@ new DomRouterBridge(
 ): DomRouterBridge;
 ```
 
-Defined in: [play-dom-router/src/dom-router-bridge.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/dom-router-bridge.ts#L40)
+Defined in: [play-dom-router/src/dom-router-bridge.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom-router/src/dom-router-bridge.ts#L40)
 
 #### Parameters
 
@@ -71,7 +71,7 @@ Defined in: [play-dom-router/src/dom-router-bridge.ts:40](https://gitlab.com/xma
 get basePath(): string;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:282](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/router-bridge-base.ts#L282)
+Defined in: [play-router/src/router-bridge-base.ts:282](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-router/src/router-bridge-base.ts#L282)
 
 The resolved URL prefix that the machine of this bridge is mounted under, or `""`
 when the machine owns the complete router.
@@ -96,7 +96,7 @@ The resolved URL prefix of the mount, or `""` when the machine owns the complete
 get basePathParams(): Readonly<Record<string, string>>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:311](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/router-bridge-base.ts#L311)
+Defined in: [play-router/src/router-bridge-base.ts:311](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-router/src/router-bridge-base.ts#L311)
 
 The resolved values of the `:param` segments of the mount, or `{}` for a prefix
 without a param.
@@ -147,7 +147,7 @@ mount while the machine stays on the same route, and no event goes out.
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:533](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/router-bridge-base.ts#L533)
+Defined in: [play-router/src/router-bridge-base.ts:533](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-router/src/router-bridge-base.ts#L533)
 
 Connects the router bridge to the Actor.
 
@@ -181,7 +181,7 @@ An adapter that needs a different behavior of the first synchronization override
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:791](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/router-bridge-base.ts#L791)
+Defined in: [play-router/src/router-bridge-base.ts:795](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-router/src/router-bridge-base.ts#L795)
 
 Disconnects the router bridge from the Actor.
 
@@ -204,7 +204,7 @@ framework.
 setBasePath(basePath?, basePathParams?): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:351](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/router-bridge-base.ts#L351)
+Defined in: [play-router/src/router-bridge-base.ts:351](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-router/src/router-bridge-base.ts#L351)
 
 Moves the machine to a different mount point, while it stays connected.
 

package/api/@xmachines/play-dom-router/classes/RouteMap.md

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:176](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/base-route-map.ts#L176)
+Defined in: [play-router/src/base-route-map.ts:176](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-router/src/base-route-map.ts#L176)
 
 The shared base class of the route map for both directions.
 
@@ -64,7 +64,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/base-route-map.ts#L209)
+Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-router/src/base-route-map.ts#L209)
 
 Builds a route map from an array of the mappings between a state ID and a path.
 
@@ -92,7 +92,7 @@ candidates is therefore efficient.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:322](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/base-route-map.ts#L322)
+Defined in: [play-router/src/base-route-map.ts:322](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-router/src/base-route-map.ts#L322)
 
 Returns the path pattern of a state ID.
 
@@ -128,7 +128,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:277](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/base-route-map.ts#L277)
+Defined in: [play-router/src/base-route-map.ts:277](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-router/src/base-route-map.ts#L277)
 
 Resolves a URL path to its state ID.
 

package/api/@xmachines/play-dom-router/functions/connectRouter.md

@@ -6,7 +6,7 @@
 function connectRouter(options): RouterConnection;
 ```
 
-Defined in: [play-dom-router/src/connect-router.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/connect-router.ts#L64)
+Defined in: [play-dom-router/src/connect-router.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom-router/src/connect-router.ts#L64)
 
 Connects the vanilla router to an actor. This is a pure browser integration.
 

package/api/@xmachines/play-dom-router/functions/createBrowserHistory.md

@@ -6,7 +6,7 @@
 function createBrowserHistory(options): BrowserHistory;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:137](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L137)
+Defined in: [play-dom-router/src/create-browser-history.ts:137](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom-router/src/create-browser-history.ts#L137)
 
 Creates a browser history that wraps window.history
 

package/api/@xmachines/play-dom-router/functions/createRouter.md

@@ -6,7 +6,7 @@
 function createRouter(options): VanillaRouter;
 ```
 
-Defined in: [play-dom-router/src/create-router.ts:79](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-router.ts#L79)
+Defined in: [play-dom-router/src/create-router.ts:79](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom-router/src/create-router.ts#L79)
 
 Creates the vanilla router for a framework-agnostic routing.
 

package/api/@xmachines/play-dom-router/interfaces/BasePathOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: BasePathOptions
 
-Defined in: [play-url/src/base-path.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-url/src/base-path.ts#L49)
+Defined in: [play-url/src/base-path.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-url/src/base-path.ts#L49)
 
 The base-path options that every router bridge, `connectRouter` function, and
 `PlayRouterProvider` component accepts.
@@ -24,5 +24,5 @@ connectRouter({
 
 | Property                                               | Modifier   | Type                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Defined in                                                                                                                      |
 | ------------------------------------------------------ | ---------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-basepath"></a> `basePath?`             | `readonly` | `string`                                   | The URL prefix that the routes of the machine hang off, for example `"/admin"` or `"/:machineId/play"`. A `:param` segment is a declarative convenience, so that a host keeps ONE string that mirrors its own route config. Every `:param` must have a value in [BasePathOptions.basePathParams](ConnectRouterOptions.md#property-basepathparams), because the bridge writes a real URL. An optional segment (`:param?`) and a wildcard (`*`) are therefore refused: neither of them resolves to one concrete prefix. An absent value, `""`, and `"/"` all mean "no prefix", which is the behaviour of every release before this option existed.                                                 | [play-url/src/base-path.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-url/src/base-path.ts#L63) |
-| <a id="property-basepathparams"></a> `basePathParams?` | `readonly` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of [BasePathOptions.basePath](ConnectRouterOptions.md#property-basepath). These values belong to the HOST, which wrote the prefix and resolved them, so they travel in NO `play.route` event: the machine is authoritative over its own params, and `event.params` holds what the pattern of the machine declares, and nothing else. A param of the host that shares a name with one of the machine can therefore shadow it never. A host reads them back from `bridge.basePathParams`, where they cannot go stale. A machine that needs the identity of its host takes it through the `input` of the actor, where that identity decides WHICH machine runs. | [play-url/src/base-path.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-url/src/base-path.ts#L77) |
+| <a id="property-basepath"></a> `basePath?`             | `readonly` | `string`                                   | The URL prefix that the routes of the machine hang off, for example `"/admin"` or `"/:machineId/play"`. A `:param` segment is a declarative convenience, so that a host keeps ONE string that mirrors its own route config. Every `:param` must have a value in [BasePathOptions.basePathParams](ConnectRouterOptions.md#property-basepathparams), because the bridge writes a real URL. An optional segment (`:param?`) and a wildcard (`*`) are therefore refused: neither of them resolves to one concrete prefix. An absent value, `""`, and `"/"` all mean "no prefix".                                                                                                                     | [play-url/src/base-path.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-url/src/base-path.ts#L62) |
+| <a id="property-basepathparams"></a> `basePathParams?` | `readonly` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of [BasePathOptions.basePath](ConnectRouterOptions.md#property-basepath). These values belong to the HOST, which wrote the prefix and resolved them, so they travel in NO `play.route` event: the machine is authoritative over its own params, and `event.params` holds what the pattern of the machine declares, and nothing else. A param of the host that shares a name with one of the machine can therefore shadow it never. A host reads them back from `bridge.basePathParams`, where they cannot go stale. A machine that needs the identity of its host takes it through the `input` of the actor, where that identity decides WHICH machine runs. | [play-url/src/base-path.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-url/src/base-path.ts#L76) |