@xmachines/play-dom

API / @xmachines/play-dom

Vanilla DOM renderer for XMachines Play architecture with atom-driven rendering.

Installation

pnpm add @xmachines/play-dom

Peer dependencies:

pnpm add @xmachines/core @xmachines/play @xmachines/play-atom @xstate/store @xmachines/json-render-core @xmachines/json-render-dom @xmachines/json-render-xstate

@xmachines/play is the peer of @xmachines/play-view, which this package depends on. Install ONE copy of it.

@xstate/store is the peer of @xmachines/play-atom, and not of this package: this package reads the atom through @xmachines/play-atom and imports the engine in no source file. Install ONE copy of it.

Quick Start

import { createRenderer, schema } from "@xmachines/play-dom";
import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
import { withView } from "@xmachines/play-xstate/view";
import { defineCatalog } from "@xmachines/json-render-core";
import { createMachine } from "xstate";
import { z } from "zod";
import type { ComponentFn } from "@xmachines/play-dom";

// 1. Define a catalog
const catalog = defineCatalog(schema, {
  components: {
    Home: { props: z.object({ title: z.string() }) },
    Login: { props: z.object({ title: z.string(), username: z.string().optional() }) },
  },
  actions: {
    login: { params: z.object({ username: z.string() }) },
    logout: {},
  },
});

// 2. Implement components
const Home: ComponentFn<typeof catalog, "Home"> = ({ props }) => {
  const el = document.createElement("section");
  el.textContent = props.title;
  return el;
};

const Login: ComponentFn<typeof catalog, "Login"> = ({ props, on }) => {
  const el = document.createElement("section");
  const btn = document.createElement("button");
  const submit = on("submit");
  btn.addEventListener("click", () => submit.emit());
  el.append(btn);
  return el;
};

// 3. Build the factory once (module scope)
const mount = createRenderer(catalog, { Home, Login });

// 4. Create and start an actor — states carry meta.view specs naming catalog components
const machine = createMachine({
  initial: "home",
  states: {
    home: {
      on: { "goto.login": "login" },
      meta: {
        view: {
          root: "root",
          elements: { root: { type: "Home", props: { title: "Home" }, children: [] } },
        },
      },
    },
    login: {
      meta: {
        view: {
          root: "root",
          elements: { root: { type: "Login", props: { title: "Login" }, children: [] } },
        },
      },
    },
  },
});
// `mount` needs the view capability
const actor = definePlayer({ machine, actor: compose(PlayerActor, withView) })();
actor.start();

// 5. Mount when actor and container are ready
const disconnect = mount(actor, document.getElementById("app")!);

// 6. Cleanup on teardown
disconnect();

Usage

`createRenderer` — one-call factory (recommended)

createRenderer is the simplest integration path. Call it one time at module scope, with your catalog and your component map. Then call the mount function that it returns, one time for each pair of an actor and a container.

import { createRenderer, schema } from "@xmachines/play-dom";
import { defineCatalog } from "@xmachines/json-render-core";

const catalog = defineCatalog(schema, {/* ... */});

const mount = createRenderer(catalog, { MyComponent });

// actor from the Quick Start
const disconnect = mount(actor, document.getElementById("app")!);
// Returns a cleanup function — call it to stop rendering and clear the container.
disconnect();

`createPlayUI` — the complete factory with every option

Use createPlayUI when you need a render error handler, a fallback element, a navigation integration, a computed function, or a custom check. Use it also when your code needs the registryResult value, for example for executeAction.

The factory holds the factory options (functions, validationFunctions, navigate, onRenderError, onError, and fallback) from the moment of its creation, and it applies them on every mount() call. Give the mount options (store and loading) to mount() itself.

import { defineRegistry, createPlayUI, schema } from "@xmachines/play-dom";
import { defineCatalog } from "@xmachines/json-render-core";

const catalog = defineCatalog(schema, {/* ... */});

// Home, Login, actor from the Quick Start
const registryResult = defineRegistry(catalog, {
  components: { Home, Login },
  actions: {
    login: async (params, setState) => {
      /* ... */
    },
    logout: async () => actor.send({ type: "auth.logout" }),
  },
});

const mount = createPlayUI(registryResult, {
  onRenderError: console.error,
  fallback: document.getElementById("loading")!,
  navigate: (path) => myRouter.push(path),
  functions: {
    fullName: (args) => `${args.first} ${args.last}`,
  },
});

const disconnect = mount(actor, document.getElementById("app")!);
disconnect();

`PlayRenderer` — class-based lifecycle control

Use PlayRenderer directly when you need the explicit connect() and disconnect() control, or when you integrate the renderer into a system that controls its life itself.

import { PlayRenderer, defineRegistry, schema } from "@xmachines/play-dom";

// catalog, actor from the Quick Start; components/actions as in the createPlayUI example
const registryResult = defineRegistry(catalog, { components, actions });

// container: your mount element, e.g. document.getElementById("app")!
const renderer = new PlayRenderer(container, actor, registryResult.registry, { registryResult });

renderer.connect();
// Later:
renderer.disconnect();

Controlled store mode. Give the renderer an external StateStore. The renderer then shares the state with the other parts of your application:

import { createAtom } from "@xmachines/play-atom";
import { xstateStoreStateStore } from "@xmachines/json-render-xstate";

const atom = createAtom<Record<string, unknown>>({ username: "" });
const store = xstateStoreStateStore({ atom });

// container, actor, registryResult from the previous example
const renderer = new PlayRenderer(container, actor, registryResult.registry, {
  registryResult,
  store,
});
renderer.connect();

Provider Options

Every entry point (createPlayUI and PlayRenderer) accepts the same UI-provider options, through UIProviderOptions. Each render pass puts the options into DomRenderContext. A component implementation therefore reads them at ctx.ctx.*.

`functions` — named compute functions for `$computed` prop expressions

This option permits a dynamic prop value of the form { "$computed": "name", "args": {...} } in a spec. Each function receives the resolved args object, and it returns the computed value.

const mount = createPlayUI(registryResult, {
  functions: {
    fullName: (args) => `${args.first} ${args.last}`,
    formatDate: (args) => new Date(args.iso as string).toLocaleDateString(),
  },
});

Without functions, every $computed expression resolves to undefined. Nothing throws, and the old behavior stays.

`validationFunctions` — custom field validation

This option gives the named check functions for a field check inside a component. Each function receives (value, args?). It returns true for a valid value, or false for an invalid value.

The DOM renderer has no ValidationProvider tree, and in this it is different from the framework renderers. Each component must call the check itself, with runValidationCheck or runValidation from @xmachines/json-render-core. Give ctx.ctx.validationFunctions to the call as customFunctions.

import { runValidationCheck } from "@xmachines/json-render-core";

const mount = createPlayUI(registryResult, {
  validationFunctions: {
    isEven: (value) => typeof value === "number" && value % 2 === 0,
    phoneNumber: (value) => /^\+?[\d\s\-()]{7,}$/.test(String(value)),
  },
});

// Inside a ComponentFn (catalog from the Quick Start):
const Login: ComponentFn<typeof catalog, "Login"> = ({ ctx }) => {
  const someValue = 42; // the value to validate, e.g. read from an input
  const result = runValidationCheck(
    { type: "isEven", message: "must be even" },
    { value: someValue, stateModel: {}, customFunctions: ctx.ctx.validationFunctions },
  );
  // result.valid, result.message
  return null;
};

`navigate` — programmatic navigation from action bindings

The renderer calls this callback when an action binding resolves with onSuccess: { navigate: "/path" }. The callback receives the resolved path string as its only argument. Use it with every router:

// React Router / TanStack Router / any push-based router:
const mount = createPlayUI(registryResult, {
  navigate: (path) => myRouter.push(path),
});

With a spec binding:

{
  "on": {
    "click": {
      "action": "submitForm",
      "onSuccess": { "navigate": "/dashboard" }
    }
  }
}

submitForm completes without an error, and the renderer then calls navigate("/dashboard").

A component implementation can also read the function at ctx.ctx.navigate. Use this when a navigation must start outside an action binding.

`onRenderError` — unified error handler

The handler receives (error, name) for three different classes of error:

A component render error — a ComponentFn throws synchronously during renderSpec. name is then the catalog component name, for example "Home".
An action handler rejection on the emit path — an ActionFn throws, or it returns a rejected promise, during emit(). name is then the catalog action name, for example "submitForm".
An action handler rejection on the watch path — an ActionFn rejects during a watch binding callback. name is then the catalog action name.

const mount = createPlayUI(registryResult, {
  onRenderError: (err, name) => {
    // Route to your application's error tracking
    Sentry.captureException(err, { extra: { name } });
  },
});

The order of the arguments is the same as in the RenderErrorHandler type of @xmachines/json-render-core: the error first, the name second. The framework renderers (@xmachines/json-render-solid and @xmachines/json-render-react) use the same order.

Without onRenderError, the renderer writes all three types of error to console.error, then stops them. No exception goes to the caller, and no promise rejection stays unhandled.

The renderer contains a failed rebuild — a change of behaviour in 2.3.0

Read this if you catch what mount() or connect() throws.

In 2.2.0 the renderer had no containment. A view that failed the rebuild threw out of mount() and out of the callback of the atom watcher, so a try of the host, an error boundary of the framework around it, or the global handler of the page received it.

In 2.3.0 the renderer contains such a failure ALWAYS. No option turns the containment on, and no option turns it off. The renderer clears the container, it shows the fallback, and mount() returns normally. A host that shows its own error page from a catch around mount() sees that catch never again.

The four framework renderers contain a failed render always, because an error boundary of a framework is not an option that a caller turns off. This change puts play-dom on the same rule.

To escalate a failure, raise it from a task of your own. The example imports rethrowLater from @xmachines/core/utils. Install that package next to this one, because your code imports it and a package manager such as pnpm does not let your code import a package that it does not declare:

import { rethrowLater } from "@xmachines/core/utils";

const mount = createPlayUI(registryResult, {
  onError: (err) => {
    reportToSentry(err);
    rethrowLater(err); // the page keeps its own global handler
  },
});

A throw that leaves the handler itself reaches no caller. The renderer contains it and writes it to console.error, exactly as the four framework renderers do. The five hold this one rule, so a host learns it one time and writes the same handler for each of them.

`onError` — the failure of a complete rebuild

onRenderError covers one element: the inner renderer contains a render error of a component, and a rejection of an action handler, per element, and the rebuild continues. Some failures escape that boundary — a $computed function that throws during the resolution of a prop, for example — and they abort the complete rebuild.

onError receives such a failure. The renderer contains it with this option and without it: it resets the state of the failed rebuild, so that the next emission makes a complete render again, and it clears the container. connect() renders the first view synchronously, so a bad initial view makes connect() throw no more.

A write of the store takes the same path. The renderer resolves the props of every element that the write touched, so a $computed function that throws on the new state aborts that render too. The renderer contains such a failure as well, and the action handler that wrote the state receives no exception.

The second parameter is the reset, for a retry that the host starts. It renders the view that the actor holds at the moment of the call, so a retry cannot rewind the screen to the view that failed. A reset that the host calls from inside the handler does nothing, because no input changed between the two attempts, and a reset after the provider goes away does nothing. The five renderers hold the same three rules.

A reset of PlayRenderer belongs to ONE connection. connect() starts a connection, and the reset of a report of an older connection does nothing. A host that calls connect() again from inside the handler abandons the connection that reported. The “Retry” button of that report must not render into the connection that took its place. Call the reset of the newest report.

A fourth rule holds in all five: each of them CONTAINS a handler that throws, and writes the throw to console.error. A host that must escalate raises the failure from a task of its own, as the section above shows.

const mount = createPlayUI(registryResult, {
  onError: (err) => reportToSentry(err),
  fallback: document.getElementById("crashed")!,
});

createPlayUI adds the parity with the framework providers: the renderer contains the failure, and it appends the fallback to the container that the failed rebuild left clear. A later view that renders clears the container again, which removes the fallback.

onError says WHERE the report goes, and fallback says what the empty container shows. Neither option turns the containment on. Without onError the renderer writes the contained error to console.error, in the same way as it does for a component that throws without an onRenderError handler. Give onError to send the failure to your own observability tool instead.

One fallback element belongs to one mount. appendChild moves a node. Two mounts of the same factory therefore take the element from each other on every null view, and the container of the first one goes empty without a notice. Build one element for each mount() call.

A fallback producer that throws is contained too — on a null view and after a failed rebuild alike — and it reports to console.error and NOT to onError. After a failed rebuild the renderer calls the producer from inside the containment of the view, so a second trip through onError would report the failure of your fallback as a failure of the view. The container stays empty, and the renderer renders the next view that works.

A component implementation can also read the handler at ctx.ctx.onRenderError. A component therefore sends its own internal errors through the same channel:

// catalog from the Quick Start; doSomethingRisky: your render logic that may throw
const Home: ComponentFn<typeof catalog, "Home"> = ({ ctx }) => {
  try {
    const el = doSomethingRisky();
    return el;
  } catch (err) {
    ctx.ctx.onRenderError?.(err, "Home");
    return null;
  }
};

API Summary

XMachines Layer

Export	Kind	Description
`createRenderer(catalog, components)`	function	The one-call factory. Its `mount` hands a plain release back
`createPlayUI(registryResult, options?)`	function	The complete factory. It returns a `MountFn`
`PlayRenderer`	class	The renderer class, with a `connect()` and `disconnect()` lifecycle
`defineRegistry(catalog, options)`	function	Build a catalog-typed `DomRegistry` with typed handlers
`renderSpec(...)`	function	The pure low-level Spec → DOM renderer
`schema`	const	The `@xmachines/json-render-dom` schema — pass to `defineCatalog()`

Key Types

Type	Description
`ComponentFn<C, K>`	Catalog-typed component function — returns `HTMLElement \| Text \| null`
`ComponentContext<C, K>`	The context of each component: `props`, `children`, `emit`, `on`, `bindings`, and `ctx`
`ActionFn<C, K>`	Catalog-typed action function — receives `(params, setState, state)`
`EventHandle`	The handle that `on(eventName)` returns. It has `emit()`, `shouldPreventDefault`, and `bound`
`SetState`	State updater: `(prev => next) => void`
`DefineRegistryResult`	The result of `defineRegistry`. It has `registry`, `handlers`, and `executeAction`
`PlayDomOptions`	Options for `PlayRenderer` — extends `UIProviderOptions`, adds `fallback` and `onError`
`CreatePlayUIOptions`	Options for `createPlayUI` — extends `UIProviderOptions`, adds `fallback` and `onError`
`MountOptions`	Per-mount options for `MountFn`: `store`, `loading`
`MountFn`	The mount: `(actor, container, options?) → () => void`. `createPlayUI` returns one, and a consumer may write one
`UIProviderOptions`	Shared options: `functions`, `validationFunctions`, `navigate`, `onRenderError`
`BaseComponentProps<P>`	Catalog-agnostic component props for shared component libraries
`DomRegistry`	Raw registry type: `Record<string, DomComponentRenderer>`
`DomSchema`	Type of the `schema` export

Rendering Behavior

The first render is synchronous — the renderer fills the container before connect() returns.
An atom-driven render waits for a microtask — watchAtom puts each update on the next tick of the microtask queue.
A null view clears the container, and the renderer then shows the fallback element when you give one. It shows it for every null view, and not for the first mount only — the four framework providers hold the same rule for their placeholder content.
A second connect() is safe — a connect() call on a connected renderer disconnects it first.
disconnect() clears the container and cancels every atom watcher and store watcher.

@xmachines/play-dom — the vanilla DOM renderer of the XMachines Play architecture.

The public API has two layers:

The XMachines layer, in this package:

createRenderer() — the one-call factory. It returns mount(actor, container, options?) → disconnect
createPlayUI() — the complete factory, with every option. It returns a MountFn
PlayRenderer — the renderer class, with a connect() and disconnect() lifecycle
PlayDomOptions, CreatePlayUIOptions, MountFn, MountOptions

The json-render layer, re-exported from @xmachines/json-render-dom:

defineRegistry — it builds a catalog-typed DomRegistry
renderSpec — the pure Spec → DOM renderer. It uses resolveElementProps of the core
ComponentFn — the catalog-typed type of a component function
ComponentContext — the catalog-typed render context: props, emit, on, children, bindings
ComponentRegistry — the catalog-typed input type of the registry
DomComponentRenderer — the raw renderer type of one element
DomRegistry — the raw registry type
DomRenderContext — the raw render context
EventHandle — the event handle that on() returns
SetState — the state updater function of an ActionFn
CatalogHasActions — the conditional type. It is true when the catalog declares an action
BaseComponentProps — the base props type of a catalog component definition

@xmachines/play-dom

Installation

Quick Start

Usage

`createRenderer` — one-call factory (recommended)

`createPlayUI` — the complete factory with every option

`PlayRenderer` — class-based lifecycle control

Provider Options

`functions` — named compute functions for `$computed` prop expressions

`validationFunctions` — custom field validation

`navigate` — programmatic navigation from action bindings

`onRenderError` — unified error handler

The renderer contains a failed rebuild — a change of behaviour in 2.3.0

`onError` — the failure of a complete rebuild

API Summary

XMachines Layer

Key Types

Rendering Behavior

Classes

Interfaces

Type Aliases

Variables

Functions

@xmachines/play-dom

Installation

Quick Start

Usage

createRenderer — one-call factory (recommended)

createPlayUI — the complete factory with every option

PlayRenderer — class-based lifecycle control

Provider Options

functions — named compute functions for $computed prop expressions

validationFunctions — custom field validation

navigate — programmatic navigation from action bindings

onRenderError — unified error handler

The renderer contains a failed rebuild — a change of behaviour in 2.3.0

onError — the failure of a complete rebuild

API Summary

XMachines Layer

Key Types

Rendering Behavior

Classes

Interfaces

Type Aliases

Variables

Functions

`createRenderer` — one-call factory (recommended)

`createPlayUI` — the complete factory with every option

`PlayRenderer` — class-based lifecycle control

`functions` — named compute functions for `$computed` prop expressions

`validationFunctions` — custom field validation

`navigate` — programmatic navigation from action bindings

`onRenderError` — unified error handler

`onError` — the failure of a complete rebuild