@xmachines/play-xstate 1.0.0-beta.2 → 1.0.0-beta.21

package/dist/routing/build-url.js

@@ -1,27 +1,34 @@
 import { isAbsoluteRoute } from "./derive-route.js";
+import { MissingRouteParamError } from "../errors.js";
 /**
- * Build full URL from route template and context
+ * Build a full URL from a route template and the actor's context.
  *
- * Per CONTEXT.md:
- * - "currentRoute derivation: Full URL generation including query params, hash, base path"
- * - "Parameters: String template syntax — /user/:id"
- * - "Inheritance: relative paths inherit parent route"
+ * Substitutes `:param` and `:param?` placeholders from `context.routeParams`
+ * or flat `context` values, then appends query params and hash fragments.
  *
- * Per RESEARCH.md Pattern 3: Replace :param with context values
+ * Parameter lookup order for each placeholder:
+ * 1. `context.routeParams[param]` — preferred when the state machine stores
+ *    route parameters in a dedicated sub-object
+ * 2. `context[param]` — flat context fallback
+ *
+ * @param routeTemplate - Route path template, e.g. `"/profile/:userId"` or
+ *   `"/settings/:section?"`.
+ * @param context - Actor context object containing parameter values, optional
+ *   `query` record, optional `hash` string, and optional `basePath` prefix.
+ * @returns The fully resolved URL string.
+ *
+ * @throws {MissingRouteParamError} When a **required** `:param` placeholder has no
+ *   matching value in context. Optional parameters (`:param?`) are silently omitted
+ *   when missing. Import the class from `@xmachines/play-xstate/errors`.
  *
  * @example
  * ```typescript
- * const url = buildRouteUrl('/user/:id', {
- *   id: '123',
- *   query: { tab: 'profile' },
- *   hash: 'section-1'
- * });
- * // Result: '/user/123?tab=profile#section-1'
- * ```
+ * buildRouteUrl("/user/:id", { id: "123", query: { tab: "profile" }, hash: "top" });
+ * // → "/user/123?tab=profile#top"
  *
- * @param routeTemplate - Route path with :param placeholders
- * @param context - Route context with parameters, query, hash
- * @returns Full URL string
+ * buildRouteUrl("/settings/:section?", {});
+ * // → "/settings"  (optional param omitted)
+ * ```
  */
 export const buildRouteUrl = (routeTemplate, context = {}) => {
     // Handle relative vs absolute paths
@@ -33,7 +40,8 @@ export const buildRouteUrl = (routeTemplate, context = {}) => {
     url = substituteParams(url, context);
     // Append query params from context
     if (context.query && typeof context.query === "object") {
-        const params = new URLSearchParams(context.query);
+        const stringEntries = Object.entries(context.query).map(([k, v]) => [k, String(v)]);
+        const params = new URLSearchParams(stringEntries);
         const queryString = params.toString();
         if (queryString) {
             url += `?${queryString}`;
@@ -61,6 +69,7 @@ export const buildRouteUrl = (routeTemplate, context = {}) => {
  * @param template - URL template with :param or :param? syntax
  * @param context - Context with parameter values (may have routeParams field)
  * @returns URL with parameters substituted and double slashes cleaned
+ * @throws {MissingRouteParamError} When a required route parameter is missing
  */
 const substituteParams = (template, context) => {
     // Replace parameters, handling optional syntax
@@ -78,9 +87,7 @@ const substituteParams = (template, context) => {
             hasOptionalRemoval = true;
             return ""; // Will leave // in path, cleaned up below
         }
-        // Required parameter missing - warn and use empty string
-        console.warn(`Route parameter '${param}' not found in context. Template: ${template}`);
-        return "";
+        throw new MissingRouteParamError(param, template);
     });
     // Clean up double slashes
     let cleaned = result.replace(/\/+/g, "/");

package/dist/routing/build-url.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-url.js","sourceRoot":"","sources":["../../src/routing/build-url.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,aAAqB,EAAE,UAAwB,EAAE,EAAU,EAAE;IAC1F,oCAAoC;IACpC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;IACxC,MAAM,UAAU,GAAG,eAAe,CAAC,aAAa,CAAC,CAAC;IAElD,iBAAiB;IACjB,IAAI,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IAE1E,qCAAqC;IACrC,GAAG,GAAG,gBAAgB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAErC,mCAAmC;IACnC,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxD,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,OAAO,CAAC,KAAY,CAAC,CAAC;QACzD,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,IAAI,WAAW,EAAE,CAAC;YACjB,GAAG,IAAI,IAAI,WAAW,EAAE,CAAC;QAC1B,CAAC;IACF,CAAC;IAED,2BAA2B;IAC3B,IAAI,OAAO,CAAC,IAAI,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtD,GAAG,IAAI,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,OAAO,GAAG,CAAC;AACZ,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,gBAAgB,GAAG,CAAC,QAAgB,EAAE,OAAqB,EAAU,EAAE;IAC5E,+CAA+C;IAC/C,IAAI,kBAAkB,GAAG,KAAK,CAAC;IAC/B,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;QAC3E,8DAA8D;QAC9D,MAAM,KAAK,GAAI,OAAe,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;QAEtE,kDAAkD;QAClD,wDAAwD;QACxD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YAC3D,OAAO,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1C,CAAC;QAED,0EAA0E;QAC1E,IAAI,QAAQ,KAAK,GAAG,EAAE,CAAC;YACtB,kBAAkB,GAAG,IAAI,CAAC;YAC1B,OAAO,EAAE,CAAC,CAAC,0CAA0C;QACtD,CAAC;QAED,yDAAyD;QACzD,OAAO,CAAC,IAAI,CAAC,oBAAoB,KAAK,qCAAqC,QAAQ,EAAE,CAAC,CAAC;QACvF,OAAO,EAAE,CAAC;IACX,CAAC,CAAC,CAAC;IAEH,0BAA0B;IAC1B,IAAI,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE1C,+DAA+D;IAC/D,2EAA2E;IAC3E,IAAI,kBAAkB,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACjD,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAChC,CAAC;IAED,OAAO,OAAO,CAAC;AAChB,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,SAAS,GAAG,CAAC,IAAY,EAAE,QAAgB,EAAU,EAAE;IAC5D,kCAAkC;IAClC,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAE/C,qCAAqC;IACrC,MAAM,kBAAkB,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAEvD,yBAAyB;IACzB,OAAO,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,IAAI,kBAAkB,EAAE,CAAC,CAAC,CAAC,IAAI,kBAAkB,EAAE,CAAC;AAC9F,CAAC,CAAC"}
+{"version":3,"file":"build-url.js","sourceRoot":"","sources":["../../src/routing/build-url.ts"],"names":[],"mappings":"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"}

package/dist/routing/derive-route.d.ts

@@ -72,7 +72,7 @@
  * console.log(route); // "/dashboard"
  * ```
  *
- * @see {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md | RFC Play v1}
+ * @see [Play RFC](../../../docs/rfc/play.md)
  * @see {@link buildRouteUrl} for URL construction with parameter substitution
  * @see {@link isAbsoluteRoute} for checking path absoluteness
  *
@@ -85,7 +85,7 @@
  * not all states need routes. For example, intermediate loading states or substates may
  * not correspond to distinct URLs.
  */
-export declare const deriveRoute: (stateMeta: Record<string, any>) => string | null;
+export declare const deriveRoute: (stateMeta: Record<string, unknown>) => string | null;
 /**
  * Check if route path is absolute
  *

package/dist/routing/derive-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive-route.d.ts","sourceRoot":"","sources":["../../src/routing/derive-route.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,eAAO,MAAM,WAAW,GAAI,WAAW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,MAAM,GAAG,IAYrE,CAAC;AA2BF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,OAE9C,CAAC"}
+{"version":3,"file":"derive-route.d.ts","sourceRoot":"","sources":["../../src/routing/derive-route.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,eAAO,MAAM,WAAW,GAAI,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,GAAG,IAYzE,CAAC;AA2BF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,OAE9C,CAAC"}

package/dist/routing/derive-route.js

@@ -72,7 +72,7 @@
  * console.log(route); // "/dashboard"
  * ```
  *
- * @see {@link https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md | RFC Play v1}
+ * @see [Play RFC](../../../docs/rfc/play.md)
  * @see {@link buildRouteUrl} for URL construction with parameter substitution
  * @see {@link isAbsoluteRoute} for checking path absoluteness
  *
@@ -88,10 +88,10 @@
 export const deriveRoute = (stateMeta) => {
     // Iterate through active state nodes to find route information
     for (const [_stateId, meta] of Object.entries(stateMeta)) {
-        if (!meta)
+        if (typeof meta !== "object" || meta === null)
             continue;
         // Check meta.route for routable states
-        if (meta.route) {
+        if ("route" in meta && meta.route) {
             return normalizeRoute(meta.route);
         }
     }

package/dist/routing/derive-route.js.map

@@ -1 +1 @@
-{"version":3,"file":"derive-route.js","sourceRoot":"","sources":["../../src/routing/derive-route.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,SAA8B,EAAiB,EAAE;IAC5E,+DAA+D;IAC/D,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1D,IAAI,CAAC,IAAI;YAAE,SAAS;QAEpB,uCAAuC;QACvC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAChB,OAAO,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnC,CAAC;IACF,CAAC;IAED,OAAO,IAAI,CAAC;AACb,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,cAAc,GAAG,CAAC,KAAoB,EAAU,EAAE;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACd,CAAC;IAED,kCAAkC;IAClC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;QAC3D,OAAQ,KAAqB,CAAC,IAAI,CAAC;IACpC,CAAC;IAED,MAAM,IAAI,KAAK,CACd,2BAA2B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,uCAAuC,CACvF,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAY,EAAW,EAAE;IACxD,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC,CAAC"}
+{"version":3,"file":"derive-route.js","sourceRoot":"","sources":["../../src/routing/derive-route.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,SAAkC,EAAiB,EAAE;IAChF,+DAA+D;IAC/D,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1D,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;YAAE,SAAS;QAExD,uCAAuC;QACvC,IAAI,OAAO,IAAI,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACnC,OAAO,cAAc,CAAC,IAAI,CAAC,KAAsB,CAAC,CAAC;QACpD,CAAC;IACF,CAAC;IAED,OAAO,IAAI,CAAC;AACb,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,cAAc,GAAG,CAAC,KAAoB,EAAU,EAAE;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACd,CAAC;IAED,kCAAkC;IAClC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;QAC3D,OAAQ,KAAqB,CAAC,IAAI,CAAC;IACpC,CAAC;IAED,MAAM,IAAI,KAAK,CACd,2BAA2B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,uCAAuC,CACvF,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAY,EAAW,EAAE;IACxD,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC,CAAC"}

package/dist/routing/format-play-route-transitions.d.ts

@@ -1,3 +1,40 @@
+/**
+ * Minimal structural shape of a single XState state node as read by
+ * `formatPlayRouteTransitions` when crawling the machine config.
+ *
+ * Only the fields the function actually inspects are typed here; all other
+ * state-node fields (e.g. `on`, `entry`, `after`) pass through unmodified via
+ * the index signature.
+ */
+export type RouteStateNode = {
+    /** Optional explicit state ID (e.g. `"home"`, `"settings"`). Used as the `#id` target in `play.route` events. */
+    id?: string;
+    /** State metadata — `meta.route` marks the state as routable. */
+    meta?: {
+        /** URL path template (e.g. `"/profile/:username"`, `"/settings/:section?"`). */
+        route?: string;
+    };
+    /** Nested child states, recursively crawled for additional route declarations. */
+    states?: Record<string, RouteStateNode>;
+    [key: string]: unknown;
+};
+/**
+ * Minimal structural constraint for machine configs accepted by
+ * `formatPlayRouteTransitions`.
+ *
+ * This is intentionally loose so the function accepts both the bare `createMachine`
+ * config object and the stricter `setup().createMachine` config without requiring
+ * any type casts at the call site. The generic `T extends RouteMachineConfig`
+ * parameter on `formatPlayRouteTransitions` preserves the original concrete type
+ * through the transform, so the return value remains directly usable by
+ * `setup().createMachine()`.
+ */
+export type RouteMachineConfig = {
+    context?: unknown;
+    states?: Record<string, unknown> | undefined;
+    on?: Record<string, unknown> | undefined;
+    [key: string]: unknown;
+};
 /**
  * Formats play.route transitions from declarative route configs
  *
@@ -6,7 +43,7 @@
  *
  * Inspired by XState's internal formatRouteTransitions (stateUtils.ts line 391).
  *
- * Usage:
+ * @example
  * ```typescript
  * const machineConfig = {
  *   id: "myMachine",
@@ -24,8 +61,8 @@
  * - Target the appropriate state
  * - Assign routeParams and queryParams from the event to context
  *
- * @param machineConfig - XState machine config (before createMachine)
- * @returns Machine config with auto-generated play.route handlers
+ * @param machineConfig - XState machine config (before createMachine). Must extend `RouteMachineConfig`.
+ * @returns The same machine config with auto-generated `play.route` handlers merged in, preserving the original type `T`.
  */
-export declare function formatPlayRouteTransitions(machineConfig: any): any;
+export declare function formatPlayRouteTransitions<T extends RouteMachineConfig>(machineConfig: T): T;
 //# sourceMappingURL=format-play-route-transitions.d.ts.map

package/dist/routing/format-play-route-transitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format-play-route-transitions.d.ts","sourceRoot":"","sources":["../../src/routing/format-play-route-transitions.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,GAAG,GAAG,GAAG,CA6ClE"}
+{"version":3,"file":"format-play-route-transitions.d.ts","sourceRoot":"","sources":["../../src/routing/format-play-route-transitions.ts"],"names":[],"mappings":"AAYA;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B,iHAAiH;IACjH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,IAAI,CAAC,EAAE;QACN,gFAAgF;QAChF,KAAK,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACxC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB,CAAC;AASF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACzC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,kBAAkB,EAAE,aAAa,EAAE,CAAC,GAAG,CAAC,CAiD5F"}

package/dist/routing/format-play-route-transitions.js

@@ -7,7 +7,7 @@ import { assign } from "xstate";
  *
  * Inspired by XState's internal formatRouteTransitions (stateUtils.ts line 391).
  *
- * Usage:
+ * @example
  * ```typescript
  * const machineConfig = {
  *   id: "myMachine",
@@ -25,20 +25,22 @@ import { assign } from "xstate";
  * - Target the appropriate state
  * - Assign routeParams and queryParams from the event to context
  *
- * @param machineConfig - XState machine config (before createMachine)
- * @returns Machine config with auto-generated play.route handlers
+ * @param machineConfig - XState machine config (before createMachine). Must extend `RouteMachineConfig`.
+ * @returns The same machine config with auto-generated `play.route` handlers merged in, preserving the original type `T`.
  */
 export function formatPlayRouteTransitions(machineConfig) {
     const routeTransitions = [];
     const collectRoutes = (states, parentPath = "") => {
         Object.entries(states).forEach(([key, stateConfig]) => {
-            const stateId = stateConfig.id || (parentPath ? `${parentPath}.${key}` : key);
-            if (stateConfig.meta?.route && stateConfig.id) {
-                // Generate transition for this routable state
+            const node = stateConfig;
+            // Build the full key-based path from the root for the transition target
+            // (XState targets use the state key hierarchy, not explicit IDs)
+            const statePath = parentPath ? `${parentPath}.${key}` : key;
+            if (node.meta?.route && node.id) {
                 const transition = {
-                    target: `.${key}`, // Relative target from root
-                    guard: ({ event }) => event.to === `#${stateConfig.id}`,
-                    reenter: true, // Enable context updates on self-transitions
+                    target: `.${statePath}`,
+                    guard: ({ event }) => event.to === `#${node.id}`,
+                    reenter: true,
                     actions: assign({
                         routeParams: ({ event }) => event.params || {},
                         queryParams: ({ event }) => event.query || {},
@@ -46,23 +48,24 @@ export function formatPlayRouteTransitions(machineConfig) {
                 };
                 routeTransitions.push(transition);
             }
-            // Recursively collect from child states
-            if (stateConfig.states) {
-                collectRoutes(stateConfig.states, stateId);
+            if (node.states) {
+                collectRoutes(node.states, statePath);
             }
         });
     };
-    if (machineConfig.states) {
-        collectRoutes(machineConfig.states);
+    const machineStates = machineConfig.states;
+    if (machineStates) {
+        collectRoutes(machineStates);
     }
-    // Add play.route handler to root if we found any routes
     if (routeTransitions.length > 0) {
+        const existingOn = machineConfig.on || {};
+        const updatedOn = {
+            ...existingOn,
+            "play.route": routeTransitions,
+        };
         return {
             ...machineConfig,
-            on: {
-                ...machineConfig.on,
-                "play.route": routeTransitions,
-            },
+            on: updatedOn,
         };
     }
     return machineConfig;

package/dist/routing/format-play-route-transitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"format-play-route-transitions.js","sourceRoot":"","sources":["../../src/routing/format-play-route-transitions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,0BAA0B,CAAC,aAAkB;IAC5D,MAAM,gBAAgB,GAAU,EAAE,CAAC;IAEnC,MAAM,aAAa,GAAG,CAAC,MAA2B,EAAE,UAAU,GAAG,EAAE,EAAE,EAAE;QACtE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,WAAW,CAAC,EAAE,EAAE;YACrD,MAAM,OAAO,GAAG,WAAW,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAE9E,IAAI,WAAW,CAAC,IAAI,EAAE,KAAK,IAAI,WAAW,CAAC,EAAE,EAAE,CAAC;gBAC/C,8CAA8C;gBAC9C,MAAM,UAAU,GAAG;oBAClB,MAAM,EAAE,IAAI,GAAG,EAAE,EAAE,4BAA4B;oBAC/C,KAAK,EAAE,CAAC,EAAE,KAAK,EAAkB,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,IAAI,WAAW,CAAC,EAAE,EAAE;oBACvE,OAAO,EAAE,IAAI,EAAE,6CAA6C;oBAC5D,OAAO,EAAE,MAAM,CAAC;wBACf,WAAW,EAAE,CAAC,EAAE,KAAK,EAAkB,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE;wBAC9D,WAAW,EAAE,CAAC,EAAE,KAAK,EAAkB,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE;qBAC7D,CAAC;iBACF,CAAC;gBAEF,gBAAgB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACnC,CAAC;YAED,wCAAwC;YACxC,IAAI,WAAW,CAAC,MAAM,EAAE,CAAC;gBACxB,aAAa,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC5C,CAAC;QACF,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC;IAEF,IAAI,aAAa,CAAC,MAAM,EAAE,CAAC;QAC1B,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IAED,wDAAwD;IACxD,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,OAAO;YACN,GAAG,aAAa;YAChB,EAAE,EAAE;gBACH,GAAG,aAAa,CAAC,EAAE;gBACnB,YAAY,EAAE,gBAAgB;aAC9B;SACD,CAAC;IACH,CAAC;IAED,OAAO,aAAa,CAAC;AACtB,CAAC"}
+{"version":3,"file":"format-play-route-transitions.js","sourceRoot":"","sources":["../../src/routing/format-play-route-transitions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AA0DhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,0BAA0B,CAA+B,aAAgB;IACxF,MAAM,gBAAgB,GAAsB,EAAE,CAAC;IAE/C,MAAM,aAAa,GAAG,CAAC,MAA+B,EAAE,UAAU,GAAG,EAAE,EAAE,EAAE;QAC1E,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,WAAW,CAAC,EAAE,EAAE;YACrD,MAAM,IAAI,GAAG,WAA6B,CAAC;YAC3C,wEAAwE;YACxE,iEAAiE;YACjE,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;YAE5D,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;gBACjC,MAAM,UAAU,GAAoB;oBACnC,MAAM,EAAE,IAAI,SAAS,EAAE;oBACvB,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,IAAI,IAAI,CAAC,EAAE,EAAE;oBAChD,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE,MAAM,CAAC;wBACf,WAAW,EAAE,CAAC,EAAE,KAAK,EAAkB,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE;wBAC9D,WAAW,EAAE,CAAC,EAAE,KAAK,EAAkB,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE;qBAC7D,CAAC;iBACF,CAAC;gBAEF,gBAAgB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACnC,CAAC;YAED,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBACjB,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YACvC,CAAC;QACF,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC;IAEF,MAAM,aAAa,GAAG,aAAa,CAAC,MAAM,CAAC;IAC3C,IAAI,aAAa,EAAE,CAAC;QACnB,aAAa,CAAC,aAAa,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,UAAU,GAAG,aAAa,CAAC,EAAE,IAAI,EAAE,CAAC;QAC1C,MAAM,SAAS,GAAG;YACjB,GAAG,UAAU;YACb,YAAY,EAAE,gBAAgB;SAC9B,CAAC;QAEF,OAAO;YACN,GAAG,aAAa;YAChB,EAAE,EAAE,SAAS;SACR,CAAC;IACR,CAAC;IAED,OAAO,aAAa,CAAC;AACtB,CAAC"}

package/dist/routing/index.d.ts

@@ -9,5 +9,6 @@
 export { deriveRoute, isAbsoluteRoute } from "./derive-route.js";
 export { buildRouteUrl } from "./build-url.js";
 export { formatPlayRouteTransitions } from "./format-play-route-transitions.js";
-export type { RouteMetadata, RouteObject, RouteContext } from "./types.js";
+export type { RouteMachineConfig, RouteStateNode } from "./format-play-route-transitions.js";
+export type { RouteContext } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/routing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/routing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/routing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAC7F,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/routing/types.d.ts

@@ -1,18 +1,8 @@
-/**
- * Route metadata from state machine
- *
- * Per CONTEXT.md: Both simple strings and objects supported
- */
-export type RouteMetadata = string | RouteObject;
-/**
- * Route object with additional metadata
- */
 export interface RouteObject {
-    /** Route path template (e.g., '/user/:id') */
     path: string;
-    /** Additional route metadata (title, etc.) */
-    [key: string]: any;
+    [key: string]: unknown;
 }
+export type RouteMetadata = string | RouteObject;
 /**
  * Route build context from machine context
  */
@@ -20,6 +10,11 @@ export interface RouteContext {
     /** Base path for relative routes */
     basePath?: string;
     /** Route parameters to substitute */
-    [key: string]: any;
+    routeParams?: Record<string, unknown>;
+    /** Query parameters */
+    query?: Record<string, unknown>;
+    /** Hash fragment */
+    hash?: string;
+    [key: string]: unknown;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/routing/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routing/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routing/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,uBAAuB;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,oBAAoB;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB"}

package/dist/signals/index.d.ts

@@ -1,3 +1,2 @@
 export { StateSignalManager } from "./state-signal.js";
-export { scheduleMicrotask } from "./debounce.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/signals/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/signals/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/signals/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/signals/index.js

@@ -1,3 +1,2 @@
 export { StateSignalManager } from "./state-signal.js";
-export { scheduleMicrotask } from "./debounce.js";
 //# sourceMappingURL=index.js.map

package/dist/signals/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/signals/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/signals/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/signals/state-signal.d.ts

@@ -9,7 +9,7 @@ import { Signal } from "@xmachines/play-signals";
  * XState already provides coalescence - if multiple transitions occur in a single send(),
  * the subscription callback only fires once with the final state.
  */
-export declare class StateSignalManager<TSnapshot = any> {
+export declare class StateSignalManager<TSnapshot = unknown> {
     private _signal;
     constructor(initialSnapshot: TSnapshot);
     /**

package/dist/signals/state-signal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-signal.d.ts","sourceRoot":"","sources":["../../src/signals/state-signal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEjD;;;;;;;;;GASG;AACH,qBAAa,kBAAkB,CAAC,SAAS,GAAG,GAAG;IAC9C,OAAO,CAAC,OAAO,CAA0B;gBAE7B,eAAe,EAAE,SAAS;IAItC;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAEpC;IAED;;;;;;;OAOG;IACH,cAAc,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI;IAIzC;;OAEG;IACH,OAAO,IAAI,IAAI;CAGf"}
+{"version":3,"file":"state-signal.d.ts","sourceRoot":"","sources":["../../src/signals/state-signal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEjD;;;;;;;;;GASG;AACH,qBAAa,kBAAkB,CAAC,SAAS,GAAG,OAAO;IAClD,OAAO,CAAC,OAAO,CAA0B;gBAE7B,eAAe,EAAE,SAAS;IAItC;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAEpC;IAED;;;;;;;OAOG;IACH,cAAc,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI;IAIzC;;OAEG;IACH,OAAO,IAAI,IAAI;CAGf"}

package/dist/types.d.ts

@@ -1,39 +1,45 @@
-import type { AnyStateMachine } from "xstate";
+import type { AnyStateMachine, InputFrom, SnapshotFrom } from "xstate";
 import type { PlayerActor as PlayerActorClass } from "./player-actor.js";
 /**
  * Configuration for definePlayer()
- *
- * Per CONTEXT.md: Single config object with machine, catalog, options
  */
-export interface PlayerConfig<TMachine extends AnyStateMachine, TCatalog = any> {
+export interface PlayerConfig<TMachine extends AnyStateMachine> {
     /** XState v5 state machine */
     machine: TMachine;
-    /** UI component catalog (optional - allows machines without UI) */
-    catalog?: TCatalog;
     /** Lifecycle hooks and configuration */
-    options?: PlayerOptions;
+    options?: PlayerOptions<TMachine>;
 }
 /**
  * Player lifecycle hooks
  *
  * Per CONTEXT.md: Rich set of hooks for observability
  */
-export interface PlayerOptions {
+export interface PlayerOptions<TMachine extends AnyStateMachine> {
     /** Called when actor starts */
-    onStart?: (actor: any) => void;
+    onStart?: (actor: PlayerActorClass<TMachine>) => void;
     /** Called when actor stops */
-    onStop?: (actor: any) => void;
+    onStop?: (actor: PlayerActorClass<TMachine>) => void;
     /** Called on every state transition */
-    onTransition?: (actor: any, prevState: any, nextState: any) => void;
+    onTransition?: (actor: PlayerActorClass<TMachine>, prevState: SnapshotFrom<TMachine>, nextState: SnapshotFrom<TMachine>) => void;
     /** Called when state signal changes */
-    onStateChange?: (actor: any, state: any) => void;
+    onStateChange?: (actor: PlayerActorClass<TMachine>, state: SnapshotFrom<TMachine>) => void;
     /** Called on actor errors */
-    onError?: (actor: any, error: Error) => void;
+    onError?: (actor: PlayerActorClass<TMachine>, error: Error) => void;
+}
+/**
+ * Optional restore arguments for the player factory.
+ *
+ * Mirrors XState's createActor options bag while preserving the existing
+ * `createPlayer(input?)` calling convention for fresh actors.
+ */
+export interface PlayerFactoryResumeOptions<TMachine extends AnyStateMachine> {
+    /** Persisted XState snapshot used to restore actor state. */
+    snapshot?: SnapshotFrom<TMachine>;
 }
 /**
  * Factory function returned by definePlayer()
  *
  * Per CONTEXT.md: Factory supports creating multiple actor instances
  */
-export type PlayerFactory<TInput = any> = (input?: TInput) => PlayerActorClass<any>;
+export type PlayerFactory<TMachine extends AnyStateMachine> = (input?: InputFrom<TMachine>, options?: PlayerFactoryResumeOptions<TMachine>) => PlayerActorClass<TMachine>;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,IAAI,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ,SAAS,eAAe,EAAE,QAAQ,GAAG,GAAG;IAC7E,8BAA8B;IAC9B,OAAO,EAAE,QAAQ,CAAC;IAElB,mEAAmE;IACnE,OAAO,CAAC,EAAE,QAAQ,CAAC;IAEnB,wCAAwC;IACxC,OAAO,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,+BAA+B;IAC/B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;IAE/B,8BAA8B;IAC9B,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;IAE9B,uCAAuC;IACvC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,KAAK,IAAI,CAAC;IAEpE,uCAAuC;IACvC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;IAEjD,6BAA6B;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAC7C;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,gBAAgB,CAAC,GAAG,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,IAAI,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ,SAAS,eAAe;IAC7D,8BAA8B;IAC9B,OAAO,EAAE,QAAQ,CAAC;IAElB,wCAAwC;IACxC,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,QAAQ,SAAS,eAAe;IAC9D,+BAA+B;IAC/B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAEtD,8BAA8B;IAC9B,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAErD,uCAAuC;IACvC,YAAY,CAAC,EAAE,CACd,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EACjC,SAAS,EAAE,YAAY,CAAC,QAAQ,CAAC,EACjC,SAAS,EAAE,YAAY,CAAC,QAAQ,CAAC,KAC7B,IAAI,CAAC;IAEV,uCAAuC;IACvC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAE3F,6BAA6B;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACpE;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B,CAAC,QAAQ,SAAS,eAAe;IAC3E,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,QAAQ,SAAS,eAAe,IAAI,CAC7D,KAAK,CAAC,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC3B,OAAO,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,KAC1C,gBAAgB,CAAC,QAAQ,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-xstate",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.21",
   "description": "XState v5 adapter for Play Architecture",
   "keywords": [
     "actor-model",
@@ -11,41 +11,48 @@
   ],
   "license": "MIT",
   "author": "",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./errors": {
+      "source": "./src/errors.ts",
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
     }
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc --build",
-    "clean": "rm -rf dist *.tsbuildinfo",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo coverage",
+    "test": "vitest",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@xmachines/play": "1.0.0-beta.2",
-    "@xmachines/play-actor": "1.0.0-beta.2",
-    "@xmachines/play-catalog": "1.0.0-beta.2",
-    "@xmachines/play-signals": "1.0.0-beta.2",
-    "zod": "^4.3.6"
+    "@xmachines/play": "1.0.0-beta.21",
+    "@xmachines/play-actor": "1.0.0-beta.21",
+    "@xmachines/play-signals": "1.0.0-beta.21"
   },
   "devDependencies": {
-    "@statelyai/inspect": "^0.4.0"
+    "@xmachines/shared": "1.0.0-beta.21",
+    "typescript": "^5.9.3 || ^6.0.2",
+    "vitest": "^4.1.2",
+    "xstate": "^5.30.0"
   },
   "peerDependencies": {
-    "xstate": "^5.28.0"
+    "xstate": "^5.30.0"
   },
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ]
+  "_devDependencies_note": "xstate appears in both peerDependencies and devDependencies intentionally. devDependencies provides workspace resolution for local builds, tests, and typechecking. peerDependencies declares the consumer version constraint. Both are pinned to ^5.30.0 to prevent drift."
 }

package/dist/catalog/index.d.ts

@@ -1,12 +0,0 @@
-/**
- * Catalog binding and validation utilities
- *
- * Provides functions for validating component references and props
- * using Zod schemas from the catalog.
- *
- * @packageDocumentation
- */
-export { validateComponentBinding } from "./validate-binding.js";
-export { validateViewProps, mergeViewProps } from "./validate-props.js";
-export type { Catalog, CatalogEntry, ViewMetadata } from "./types.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/catalog/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/catalog/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACxE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/catalog/index.js

@@ -1,11 +0,0 @@
-/**
- * Catalog binding and validation utilities
- *
- * Provides functions for validating component references and props
- * using Zod schemas from the catalog.
- *
- * @packageDocumentation
- */
-export { validateComponentBinding } from "./validate-binding.js";
-export { validateViewProps, mergeViewProps } from "./validate-props.js";
-//# sourceMappingURL=index.js.map

package/dist/catalog/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/catalog/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/catalog/types.d.ts

@@ -1,36 +0,0 @@
-import type { z } from "zod";
-import type { Catalog as BaseCatalog } from "@xmachines/play-catalog";
-/**
- * UI component catalog entry with schema and component reference
- *
- * Per CONTEXT.md: String keys reference components, Zod schemas validate props
- */
-export interface CatalogEntry {
-    /** Zod schema for component props */
-    schema: z.ZodType<any>;
-    /** React component (or other framework component) */
-    component: any;
-}
-/**
- * Component catalog mapping
- *
- * Re-export from @xmachines/play-catalog for consistent API.
- *
- * Supports two formats:
- * - Direct Zod schemas: `Record<string, z.ZodType>` via defineCatalog()
- * - CatalogEntry objects: `Record<string, CatalogEntry>` with { schema, component }
- *
- * PlayerActor accepts either format - if entry has 'schema' property, uses CatalogEntry pattern,
- * otherwise treats as direct Zod schema.
- */
-export type Catalog = BaseCatalog | Record<string, CatalogEntry>;
-/**
- * View metadata from state machine
- */
-export interface ViewMetadata {
-    /** Component name from catalog */
-    component: string;
-    /** Additional view props/data */
-    [key: string]: any;
-}
-//# sourceMappingURL=types.d.ts.map

package/dist/catalog/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/catalog/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtE;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B,qCAAqC;IACrC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACvB,qDAAqD;IACrD,SAAS,EAAE,GAAG,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACnB"}

package/dist/catalog/types.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=types.js.map

package/dist/catalog/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/catalog/types.ts"],"names":[],"mappings":""}