@xmachines/play-dom 1.0.0-beta.32 → 1.0.0-beta.33

package/README.md

@@ -2,73 +2,256 @@
 
 **Vanilla DOM renderer for XMachines**
 
-`connectRenderer` — a framework-free `PlayRenderer` equivalent that wires an XState v5 actor's `currentView` TC39 Signal to pure DOM rendering via a catalog-typed `DomRegistry`.
+Framework-free view rendering driven by an XState v5 actor's `currentView` TC39 Signal. Implements the same catalog-typed `defineRegistry` / `ComponentFn` / `ActionFn` API surface as `@json-render/react`, `/solid`, `/vue`, and `/svelte`.
 
 ## Installation
 
 ```bash
-npm install @xmachines/play-dom
+npm install @xmachines/play-dom @json-render/core zod
 ```
 
 ## Key Exports
 
-- `connectRenderer({ actor, registry, container, handlers })` — connect actor view signal to DOM
-- `defineRegistry(catalog, { components, actions })` — build a catalog-typed `DomRegistry` with real async action handlers
-- `schema` — DOM schema for use with `defineCatalog` (mirrors `@json-render/react/schema` shape)
-- `PlayRenderer` — class-based renderer (connect/disconnect lifecycle)
-- `ComponentFn<C, K>` — catalog-typed DOM component function type
-- `ComponentContext<C, K>` — context passed to each `ComponentFn` (props, emit, on, children, bindings)
-- `renderSpec(spec, store, registry, send, handlers)` — pure Spec → DOM renderer
+| Export                                              | Description                                                                                 |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `createRenderer(catalog, componentMap)`             | One-call factory: returns `mount(actor, container, options?) → disconnect`                  |
+| `connectRenderer(options)`                          | Functional API: connect actor → DOM with full options                                       |
+| `defineRegistry(catalog, { components, actions })`  | Build a catalog-typed `DomRegistry` with typed action handlers                              |
+| `PlayRenderer`                                      | Class-based renderer — `connect()` / `disconnect()` lifecycle                               |
+| `schema`                                            | DOM schema for `defineCatalog` (mirrors `@json-render/react/schema`)                        |
+| `ComponentFn<C, K>`                                 | Catalog-typed DOM component function type                                                   |
+| `ComponentContext<C, K>`                            | Context passed to each `ComponentFn` — `props`, `on`, `emit`, `children`, `bindings`, `ctx` |
+| `ActionFn<C, K>`                                    | `(params, setState, state) => Promise<void>` — catalog-typed action handler                 |
+| `SetState`                                          | `(updater: prev => next) => void` — write to the local state store                          |
+| `BaseComponentProps<P>`                             | Base type for catalog component prop definitions                                            |
+| `CatalogHasActions<C>`                              | Conditional type: `true` when catalog declares actions                                      |
+| `renderSpec(spec, store, registry, send, handlers)` | Pure Spec → DOM renderer (advanced use)                                                     |
 
-## Usage
+## Quick Start — `createRenderer`
 
-```ts
-import { definePlayer } from "@xmachines/play-xstate";
-import { connectRenderer, defineRegistry, schema } from "@xmachines/play-dom";
+The preferred one-call pattern — mirrors all framework renderers:
+
+```typescript
+import { createRenderer, schema } from "@xmachines/play-dom";
 import { defineCatalog } from "@json-render/core";
-import { authCatalogDef, type AuthActor } from "@xmachines/play-actor-shared";
+import { z } from "zod";
 import type { ComponentFn } from "@xmachines/play-dom";
 
-// 1. Build catalog with DOM schema
-const authCatalog = defineCatalog(schema, authCatalogDef);
-type AuthCatalog = typeof authCatalog;
+// 1. Define 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: {},
+	},
+});
+type AppCatalog = typeof catalog;
 
-// 2. Implement catalog components
-const Home: ComponentFn<AuthCatalog, "Home"> = ({ props }) => {
+// 2. Implement components
+const Home: ComponentFn<AppCatalog, "Home"> = ({ props }) => {
 	const el = document.createElement("section");
 	el.textContent = props.title;
 	return el;
 };
 
-// 3. Build registry with real async action handlers
-const registryResult = defineRegistry(authCatalog, {
-	components: { Home /* ... */ },
+const Login: ComponentFn<AppCatalog, "Login"> = ({ props, on }) => {
+	const section = document.createElement("section");
+	const input = document.createElement("input");
+	input.value = props.username ?? "";
+	input.addEventListener("input", () =>
+		ctx.store.update((s) => ({ ...s, username: input.value })),
+	);
+
+	const button = document.createElement("button");
+	button.textContent = "Log In";
+	const submit = on("submit");
+	button.addEventListener("click", () => submit.emit());
+
+	section.append(input, button);
+	return section;
+};
+
+// 3. Create the renderer factory (once, at module level)
+const mount = createRenderer(catalog, { Home, Login });
+
+// 4. Mount when actor and container are ready
+const actor = createPlayer()();
+actor.start();
+
+const disconnect = mount(actor, document.getElementById("app")!);
+
+// Cleanup:
+disconnect();
+```
+
+## `defineRegistry` — Full Control
+
+When you need `registryResult.executeAction()` or want to share the registry with `connectRenderer`:
+
+```typescript
+import { defineRegistry, connectRenderer, schema } from "@xmachines/play-dom";
+import { defineCatalog } from "@json-render/core";
+import { z } from "zod";
+
+const catalog = defineCatalog(schema, {
+	components: {
+		Home: { props: z.object({ title: z.string() }) },
+	},
+	actions: {
+		login: { params: z.object({ username: z.string() }) },
+		logout: {},
+	},
+});
+
+// Action handlers receive (params, setState, state)
+// - params: resolved from the spec's on.submit.params (e.g. { $state: "/username" })
+// - setState: write to the local state store (e.g. to clear a form)
+// - state: current local state store snapshot
+const registryResult = defineRegistry(catalog, {
+	components: {
+		Home: ({ props }) => {
+			const el = document.createElement("section");
+			el.textContent = props.title;
+			return el;
+		},
+	},
 	actions: {
-		login: async (params) => {
+		login: async (params, setState) => {
 			if (!params) return;
 			actor.send({ type: "auth.login", username: params.username });
+			setState((prev) => ({ ...prev, username: "" })); // clear the form
 		},
 		logout: async () => actor.send({ type: "auth.logout" }),
 	},
 });
 
-// 4. Resolve handlers and connect
-const actor = definePlayer({ machine: authMachine })();
-actor.start();
-
-const handlers = registryResult.handlers(
-	() => undefined,
-	() => ({}),
-);
-const container = document.getElementById("app")!;
 const disconnect = connectRenderer({
 	actor,
 	registry: registryResult.registry,
-	container,
-	handlers,
+	registryResult, // wires setState/state from xstate store automatically
+	container: document.getElementById("app")!,
 });
 ```
 
+## Component API
+
+### `ComponentFn<C, K>` — component function signature
+
+```typescript
+const MyCard: ComponentFn<AppCatalog, "Card"> = ({
+	props, // catalog-typed props for this component
+	children, // Node[] — rendered child nodes
+	on, // (eventName) => EventHandle — get emit() for catalog-declared events
+	emit, // (eventName) => void — fire an event directly
+	bindings, // Record<string, string> — $bindState paths for two-way bindings
+	ctx, // DomRenderContext — store, send, handlers, loading, functions
+}) => {
+	const el = document.createElement("div");
+	el.append(...children);
+	return el;
+};
+```
+
+### Two-way binding with `$bindState`
+
+In the view spec:
+
+```json
+{ "username": { "$bindState": "/username" } }
+```
+
+In the component:
+
+```typescript
+const Login: ComponentFn<AppCatalog, "Login"> = ({ props, ctx }) => {
+	const input = document.createElement("input");
+	input.value = props.username ?? "";
+	// Write back to the store on user input
+	input.addEventListener("input", () => {
+		ctx.store.update((s) => ({ ...s, username: input.value }));
+	});
+	return input;
+};
+```
+
+### `on()` — event handle
+
+```typescript
+const submit = on("submit"); // EventHandle
+if (submit.bound) {
+	button.addEventListener("click", (e) => {
+		if (submit.shouldPreventDefault) e.preventDefault();
+		submit.emit(); // resolves params from store, calls action handler
+	});
+}
+```
+
+### `ActionFn` — action handler signature
+
+```typescript
+// Full signature — all three params are available
+login: async (params, setState, state) => {
+  actor.send({ type: "auth.login", username: params!.username });
+  setState(prev => ({ ...prev, username: "" }));
+  console.log("previous state was:", state);
+},
+
+// Params-only — setState/state can be omitted if unused
+logout: async () => actor.send({ type: "auth.logout" }),
+route: async (params) => actor.send({ type: "play.route", to: params!.to }),
+```
+
+## Spec Features
+
+`renderSpec` / `renderElement` supports these spec directives:
+
+| Directive                                              | Description                                                                           |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| `visible`                                              | Boolean or `{ $state: "/path" }` — hide element when false                            |
+| `on.submit` / `on.click`                               | Action binding — `{ action: "login", params: { username: { $state: "/username" } } }` |
+| `repeat: { statePath, key? }`                          | Render children once per item in the state array at `statePath`                       |
+| `watch: { "/path": actionBinding }`                    | Fire action when store path changes after mount                                       |
+| `props.username: { $bindState: "/username" }`          | Two-way binding — read from store, write back via `ctx.store.update()`                |
+| `props.value: { $state: "/value" }`                    | Read-only store reference                                                             |
+| `props.label: { $computed: "computeFn", args: [...] }` | Computed prop via `functions` map                                                     |
+
+## `PlayRenderer` — class API
+
+```typescript
+import { PlayRenderer, defineRegistry } from "@xmachines/play-dom";
+
+const { registry, registryResult } = defineRegistry(catalog, { components, actions });
+
+const renderer = new PlayRenderer(document.getElementById("app")!, actor, registry, {
+	registryResult,
+});
+
+renderer.connect(); // starts watching actor.currentView
+renderer.disconnect(); // stops watching, clears container
+
+// double-connect is safe — connect() calls disconnect() internally if already connected
+```
+
+## Options Reference
+
+### `ConnectRendererOptions` / `PlayDomOptions`
+
+| Option           | Type                            | Description                                                                   |
+| ---------------- | ------------------------------- | ----------------------------------------------------------------------------- |
+| `actor`          | `AbstractActor & Viewable`      | Actor providing `currentView` signal                                          |
+| `registry`       | `DomRegistry`                   | Component renderer map from `defineRegistry`                                  |
+| `registryResult` | `DefineRegistryResult`          | Preferred — auto-wires `setState`/`state` from xstate store                   |
+| `handlers`       | `Record<string, ActionHandler>` | Pre-resolved handlers (legacy / advanced)                                     |
+| `container`      | `HTMLElement`                   | DOM element to render into                                                    |
+| `fallback`       | `HTMLElement \| null`           | Shown on initial mount when view is `null` (initial mount only)               |
+| `store`          | `StateStore`                    | External store — controlled mode, overrides `spec.state`                      |
+| `loading`        | `boolean`                       | Streaming mode — suppresses missing-child warnings, exposes `ctx.ctx.loading` |
+
 ## Learn More
 
 - [DOM Router adapter `@xmachines/play-dom-router`](../play-dom-router/README.md)
+- [API reference](../../packages/docs/api/@xmachines/play-dom/README.md)
+- [Play RFC](../../packages/docs/rfc/play.md)

package/dist/PlayRenderer.d.ts

@@ -13,24 +13,37 @@ import type { AnyActorLogic } from "xstate";
 import type { DomRegistry } from "./json-render/types.js";
 import type { PlayDomOptions } from "./xm-types.js";
 /**
- * PlayRenderer connects an actor's currentView signal to the DOM renderer.
+ * PlayRenderer connects an actor's `currentView` signal to the DOM renderer.
  *
- * Usage:
+ * Watches `actor.currentView` via TC39 Signals and renders `DomComponentRenderer`
+ * functions into `container` on every view transition. Cleared on `disconnect()`.
+ *
+ * **Preferred usage — via `registryResult`:**
  * ```typescript
- * const { registry, handlers } = defineRegistry(catalog, { components, actions });
- * const resolvedHandlers = handlers(() => undefined, () => ({}));
- * const renderer = new PlayRenderer(container, actor, registry, { handlers: resolvedHandlers });
+ * import { PlayRenderer, defineRegistry } from "@xmachines/play-dom";
+ *
+ * const registryResult = defineRegistry(catalog, { components, actions });
+ * const renderer = new PlayRenderer(container, actor, registryResult.registry, {
+ *   registryResult, // wires setState/getState from xstate store automatically
+ * });
  * renderer.connect();
+ * // Later:
+ * renderer.disconnect();
+ * ```
  *
- * // Controlled mode — bring your own store:
+ * **Controlled store mode** — bring your own `StateStore`:
+ * ```typescript
  * import { createAtom } from "@xstate/store";
  * import { xstateStoreStateStore } from "@json-render/xstate";
- * const store = xstateStoreStateStore({ atom: createAtom({ username: "" }) });
- * const renderer = new PlayRenderer(container, actor, registry, { store, handlers: resolvedHandlers });
  *
- * // Later:
- * renderer.disconnect();
+ * const atom  = createAtom({ username: "" });
+ * const store = xstateStoreStateStore({ atom });
+ * const renderer = new PlayRenderer(container, actor, registry, { registryResult, store });
+ * renderer.connect();
  * ```
+ *
+ * Double `connect()` is safe — calling `connect()` while already connected
+ * automatically disconnects first, preventing double-render subscriptions.
  */
 export declare class PlayRenderer {
     private readonly container;
@@ -39,18 +52,34 @@ export declare class PlayRenderer {
     private readonly options;
     private _unwatch;
     private _storeUnsubscribe;
+    private _watchCleanups;
+    /**
+     * Set to `false` in `disconnect()` before calling `storeUnsub()`.
+     * The `rerender` closure checks this flag at entry so that any synchronous
+     * callback fired by the `StateStore` implementation within its own
+     * `unsubscribe()` call (an edge-case but valid contract) does not mutate a
+     * detached DOM tree.
+     */
+    private _alive;
     /**
-     * @param container - The `HTMLElement` to render into. Cleared and repopulated on every view transition.
-     * @param actor - Actor instance providing the `currentView` signal (must implement `Viewable`).
-     * @param registry - Map of component type names to `DomComponentRenderer` functions.
-     * @param options - Optional configuration: `handlers` map (action name → async handler) and
-     *   optional external `store` (controlled mode — when omitted, a fresh `@xstate/store` atom is
-     *   created per view transition seeded from `spec.state`).
+     * @param container - `HTMLElement` to render into. Cleared and repopulated on every view transition.
+     * @param actor     - Actor providing the `currentView` signal (must implement `Viewable`).
+     * @param registry  - Component renderer map — typically `registryResult.registry` from `defineRegistry`.
+     * @param options   - Configuration:
+     *   - `registryResult` — preferred; auto-wires `setState`/`state` from the xstate store.
+     *   - `handlers`       — pre-resolved handler map (legacy; used when `registryResult` is absent).
+     *   - `store`          — external `StateStore` (controlled mode; overrides `spec.state` seeding).
+     *   - `loading`        — streaming mode flag; suppresses missing-child warnings.
      */
     constructor(container: HTMLElement, actor: AbstractActor<AnyActorLogic> & Viewable, registry: DomRegistry, options?: PlayDomOptions);
     /**
      * Start watching actor.currentView and render to container.
      * Renders the initial view synchronously, then subscribes to signal changes.
+     *
+     * Calling `connect()` on an already-connected renderer (where a previous
+     * `connect()` was never followed by `disconnect()`) would silently install a
+     * second `watchSignal` subscription, causing double-renders on every view
+     * change. Guard against this by auto-disconnecting first.
      */
     connect(): void;
     /**

package/dist/PlayRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAgB,MAAM,uBAAuB,CAAC;AACnF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAoBpD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,YAAY;IAavB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAfzB,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,iBAAiB,CAA6B;IAEtD;;;;;;;OAOG;gBAEe,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,cAAmB;IAG9C;;;OAGG;IACH,OAAO,IAAI,IAAI;IAKf;;OAEG;IACH,UAAU,IAAI,IAAI;IAQlB,OAAO,CAAC,OAAO;CA8Bf"}
+{"version":3,"file":"PlayRenderer.d.ts","sourceRoot":"","sources":["../src/PlayRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAgB,MAAM,uBAAuB,CAAC;AACnF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,wBAAwB,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAyBpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,YAAY;IAwBvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IA1BzB,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,iBAAiB,CAA6B;IACtD,OAAO,CAAC,cAAc,CAAsB;IAC5C;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAQ;IAEtB;;;;;;;;;OASG;gBAEe,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,cAAmB;IAG9C;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI;IAMf;;OAEG;IACH,UAAU,IAAI,IAAI;IAmBlB,OAAO,CAAC,OAAO;CAuFf"}

package/dist/PlayRenderer.js

@@ -20,34 +20,52 @@ import { renderSpec } from "./json-render/renderer.js";
  * machine author put in the view spec. `createAtom` requires a plain object as
  * its initial value — anything else produces a broken store at runtime.
  *
- * Returns the value unchanged when it is a non-null object; falls back to `{}`
- * for all other cases (null, undefined, string, number, array, etc.).
+ * Only plain objects (prototype is `Object.prototype` or `null`) are accepted.
+ * Class instances and built-in objects (Date, Map, Set, etc.) are rejected and
+ * fall back to `{}` — this prevents silent broken-store bugs at runtime.
+ * Arrays are also rejected (they have `Array.prototype`).
  */
 function toAtomState(state) {
     if (state !== null && typeof state === "object" && !Array.isArray(state)) {
-        return state;
+        const proto = Object.getPrototypeOf(state);
+        if (proto === Object.prototype || proto === null) {
+            return state;
+        }
     }
     return {};
 }
 /**
- * PlayRenderer connects an actor's currentView signal to the DOM renderer.
+ * PlayRenderer connects an actor's `currentView` signal to the DOM renderer.
  *
- * Usage:
+ * Watches `actor.currentView` via TC39 Signals and renders `DomComponentRenderer`
+ * functions into `container` on every view transition. Cleared on `disconnect()`.
+ *
+ * **Preferred usage — via `registryResult`:**
  * ```typescript
- * const { registry, handlers } = defineRegistry(catalog, { components, actions });
- * const resolvedHandlers = handlers(() => undefined, () => ({}));
- * const renderer = new PlayRenderer(container, actor, registry, { handlers: resolvedHandlers });
+ * import { PlayRenderer, defineRegistry } from "@xmachines/play-dom";
+ *
+ * const registryResult = defineRegistry(catalog, { components, actions });
+ * const renderer = new PlayRenderer(container, actor, registryResult.registry, {
+ *   registryResult, // wires setState/getState from xstate store automatically
+ * });
  * renderer.connect();
+ * // Later:
+ * renderer.disconnect();
+ * ```
  *
- * // Controlled mode — bring your own store:
+ * **Controlled store mode** — bring your own `StateStore`:
+ * ```typescript
  * import { createAtom } from "@xstate/store";
  * import { xstateStoreStateStore } from "@json-render/xstate";
- * const store = xstateStoreStateStore({ atom: createAtom({ username: "" }) });
- * const renderer = new PlayRenderer(container, actor, registry, { store, handlers: resolvedHandlers });
  *
- * // Later:
- * renderer.disconnect();
+ * const atom  = createAtom({ username: "" });
+ * const store = xstateStoreStateStore({ atom });
+ * const renderer = new PlayRenderer(container, actor, registry, { registryResult, store });
+ * renderer.connect();
  * ```
+ *
+ * Double `connect()` is safe — calling `connect()` while already connected
+ * automatically disconnects first, preventing double-render subscriptions.
  */
 export class PlayRenderer {
     container;
@@ -56,13 +74,24 @@ export class PlayRenderer {
     options;
     _unwatch = null;
     _storeUnsubscribe = null;
+    _watchCleanups = [];
+    /**
+     * Set to `false` in `disconnect()` before calling `storeUnsub()`.
+     * The `rerender` closure checks this flag at entry so that any synchronous
+     * callback fired by the `StateStore` implementation within its own
+     * `unsubscribe()` call (an edge-case but valid contract) does not mutate a
+     * detached DOM tree.
+     */
+    _alive = true;
     /**
-     * @param container - The `HTMLElement` to render into. Cleared and repopulated on every view transition.
-     * @param actor - Actor instance providing the `currentView` signal (must implement `Viewable`).
-     * @param registry - Map of component type names to `DomComponentRenderer` functions.
-     * @param options - Optional configuration: `handlers` map (action name → async handler) and
-     *   optional external `store` (controlled mode — when omitted, a fresh `@xstate/store` atom is
-     *   created per view transition seeded from `spec.state`).
+     * @param container - `HTMLElement` to render into. Cleared and repopulated on every view transition.
+     * @param actor     - Actor providing the `currentView` signal (must implement `Viewable`).
+     * @param registry  - Component renderer map — typically `registryResult.registry` from `defineRegistry`.
+     * @param options   - Configuration:
+     *   - `registryResult` — preferred; auto-wires `setState`/`state` from the xstate store.
+     *   - `handlers`       — pre-resolved handler map (legacy; used when `registryResult` is absent).
+     *   - `store`          — external `StateStore` (controlled mode; overrides `spec.state` seeding).
+     *   - `loading`        — streaming mode flag; suppresses missing-child warnings.
      */
     constructor(container, actor, registry, options = {}) {
         this.container = container;
@@ -73,8 +102,15 @@ export class PlayRenderer {
     /**
      * Start watching actor.currentView and render to container.
      * Renders the initial view synchronously, then subscribes to signal changes.
+     *
+     * Calling `connect()` on an already-connected renderer (where a previous
+     * `connect()` was never followed by `disconnect()`) would silently install a
+     * second `watchSignal` subscription, causing double-renders on every view
+     * change. Guard against this by auto-disconnecting first.
      */
     connect() {
+        if (this._unwatch !== null)
+            this.disconnect();
         this._render(this.actor.currentView.get());
         this._unwatch = watchSignal(this.actor.currentView, (view) => this._render(view));
     }
@@ -84,14 +120,38 @@ export class PlayRenderer {
     disconnect() {
         this._unwatch?.();
         this._unwatch = null;
-        this._storeUnsubscribe?.();
+        // Null the refs first so any in-flight rerender callback sees null and skips.
+        // Capture the arrays/functions before clearing so we call the correct cleanups
+        // even if unsubscribing the store triggers a synchronous rerender that would
+        // otherwise overwrite _watchCleanups before we iterate them.
+        const storeUnsub = this._storeUnsubscribe;
+        const watchCleanups = [...this._watchCleanups];
         this._storeUnsubscribe = null;
+        this._watchCleanups = [];
+        // Set alive = false before calling storeUnsub() so that any synchronous
+        // rerender callback triggered within unsubscribe() exits immediately.
+        this._alive = false;
+        storeUnsub?.();
+        for (const cleanup of watchCleanups)
+            cleanup();
         this.container.replaceChildren();
     }
     _render(view) {
+        // Reset alive before releasing old subscriptions — any synchronous callback
+        // from the old store's unsubscribe sees alive=true and will be accepted.
+        // This differs from disconnect() which sets alive=false BEFORE calling storeUnsub.
+        this._alive = true;
         // Clean up previous store subscription before re-rendering
         this._storeUnsubscribe?.();
         this._storeUnsubscribe = null;
+        // Release watch cleanups from the previous view's initial render.
+        // Without this, watch subscriptions from the prior view remain active
+        // between a view transition and the first store update in the new view,
+        // holding references to stale DOM elements and preventing GC.
+        const prevWatchCleanups = this._watchCleanups;
+        this._watchCleanups = [];
+        for (const cleanup of prevWatchCleanups)
+            cleanup();
         this.container.replaceChildren();
         if (!view)
             return;
@@ -105,10 +165,39 @@ export class PlayRenderer {
                 atom: createAtom(toAtomState(view.spec.state)),
             });
         const send = this.actor.send.bind(this.actor);
-        const handlers = this.options.handlers ?? {};
+        // Build a SetState function backed by the xstate store.
+        // Called lazily at action-invocation time (not at handlers() call time)
+        // so actions always see the latest store state.
+        const setState = (updater) => {
+            const prev = store.getSnapshot();
+            const next = updater(prev);
+            // store.update() is called with a full state snapshot (not a patch map).
+            // This is compatible with createStoreAdapter/createStateStore where update()
+            // performs a shallow merge of the provided top-level keys, effectively
+            // replacing the entire state model. Do not change this to a path-keyed
+            // patch unless the StateStore contract is updated to match.
+            store.update(next);
+        };
+        // Resolve handlers: prefer registryResult (wires setState/getState from store),
+        // fall back to pre-resolved handlers map for backward compatibility.
+        const handlers = this.options.registryResult
+            ? this.options.registryResult.handlers(() => setState, () => store.getSnapshot())
+            : (this.options.handlers ?? {});
+        const loading = this.options.loading;
         const rerender = () => {
+            // Guard: skip if PlayRenderer has been disconnected.
+            // Handles the edge case where a StateStore implementation fires its
+            // subscribed callbacks synchronously within its own unsubscribe() call.
+            if (!this._alive)
+                return;
+            // Clear watch subscriptions from previous render pass before re-rendering.
+            for (const cleanup of this._watchCleanups)
+                cleanup();
+            this._watchCleanups = [];
             this.container.replaceChildren();
-            const node = renderSpec(view.spec, store, this.registry, send, handlers);
+            const node = renderSpec(view.spec, store, this.registry, send, handlers, undefined, undefined, undefined, loading, (cleanup) => {
+                this._watchCleanups.push(cleanup);
+            });
             if (node)
                 this.container.appendChild(node);
         };

package/dist/PlayRenderer.js.map

@@ -1 +1 @@
-{"version":3,"file":"PlayRenderer.js","sourceRoot":"","sources":["../src/PlayRenderer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PlayRenderer.js","sourceRoot":"","sources":["../src/PlayRenderer.ts"],"names":[],"mappings":"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"}