@xmachines/play-sveltekit-router 1.0.0-beta.24

package/README.md

@@ -0,0 +1,31 @@
+# @xmachines/play-sveltekit-router
+
+Thin SvelteKit adapter for XMachines Play.
+
+## What it does
+
+- Keeps `actor.currentRoute` and SvelteKit navigation in sync.
+- Exposes a local `RouteMap` plus `createRouteMap(machine)` helper.
+- Stays direct, with no shared `@xmachines/play-svelte-router` abstraction.
+- Extracts route params and query values when browser navigation enters through SvelteKit.
+
+## Usage
+
+```ts
+import { connectRouter, createRouteMap } from "@xmachines/play-sveltekit-router";
+
+const routeMap = createRouteMap(machine);
+const disconnect = connectRouter({ actor, routeMap });
+
+onDestroy(disconnect);
+```
+
+## Notes
+
+- `connectRouter()` returns a cleanup function. Call it during teardown to stop syncing actor updates.
+- Actor routes may be either state IDs or resolved paths; the adapter normalizes both.
+- Incoming SvelteKit paths are converted into `play.route` events with extracted `params` and `query`.
+
+## Route map
+
+`createRouteMap(machine)` reads route metadata from the machine and builds a Play route map for SvelteKit paths.

package/dist/connect-router.d.ts

@@ -0,0 +1,9 @@
+import type { AbstractActor, Routable } from "@xmachines/play-actor";
+import type { AnyActorLogic } from "xstate";
+import type { RouteMap } from "./route-map.js";
+export interface ConnectRouterOptions {
+    readonly actor: AbstractActor<AnyActorLogic> & Routable;
+    readonly routeMap: RouteMap;
+}
+export declare function connectRouter(options: ConnectRouterOptions): () => void;
+//# sourceMappingURL=connect-router.d.ts.map

package/dist/connect-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-router.d.ts","sourceRoot":"","sources":["../src/connect-router.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAK5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC;IACxD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC5B;AAaD,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAkGvE"}

package/dist/connect-router.js

@@ -0,0 +1,103 @@
+import { afterNavigate, goto } from "$app/navigation";
+import { buildPlayRouteEvent } from "@xmachines/play-router";
+import { watchSignal } from "@xmachines/play-signals";
+import { extractRouteParams, resolveConcreteActorPath, } from "@xmachines/play-svelte-router";
+function getCurrentLocation() {
+    const location = globalThis.location;
+    /* v8 ignore next */
+    if (!location)
+        return null;
+    return {
+        pathname: location.pathname,
+        search: location.search,
+    };
+}
+export function connectRouter(options) {
+    const { actor, routeMap } = options;
+    let isActive = true;
+    let isProcessingNavigation = false;
+    let lastSyncedPath = resolveConcreteActorPath(actor.currentRoute.get(), routeMap);
+    const syncActorFromRouter = (pathname, search) => {
+        if (!isActive || isProcessingNavigation)
+            return;
+        const nextRoute = buildPlayRouteEvent({
+            pathname,
+            search,
+            resolve: (sanitizedPathname) => {
+                const stateId = routeMap.getStateIdByPath(sanitizedPathname);
+                if (!stateId) {
+                    return { to: null, params: {} };
+                }
+                const pattern = routeMap.getPathByStateId(stateId);
+                return {
+                    to: stateId,
+                    params: pattern ? extractRouteParams(sanitizedPathname, pattern) : {},
+                };
+            },
+        });
+        if (!nextRoute || nextRoute.pathname === lastSyncedPath)
+            return;
+        isProcessingNavigation = true;
+        lastSyncedPath = nextRoute.pathname;
+        try {
+            actor.send(nextRoute.event);
+        }
+        finally {
+            isProcessingNavigation = false;
+        }
+    };
+    const syncRouterFromActor = (route) => {
+        /* v8 ignore next */
+        if (!isActive || isProcessingNavigation || !route)
+            return;
+        const path = resolveConcreteActorPath(route, routeMap);
+        /* v8 ignore next */
+        if (!path || path === lastSyncedPath)
+            return;
+        const location = getCurrentLocation();
+        /* v8 ignore next 4 */
+        if (location && location.pathname === path) {
+            lastSyncedPath = path;
+            return;
+        }
+        isProcessingNavigation = true;
+        lastSyncedPath = path;
+        void goto(path, { noScroll: true, keepFocus: true })
+            .then(() => {
+            // afterNavigate resets isProcessingNavigation in the normal flow.
+            // Reset here as a safety net if afterNavigate never fires (e.g. same-page goto).
+            queueMicrotask(() => {
+                isProcessingNavigation = false;
+            });
+        })
+            .catch(() => {
+            isProcessingNavigation = false;
+        });
+    };
+    const unwatchRoute = watchSignal(actor.currentRoute, (route) => {
+        syncRouterFromActor(route);
+    });
+    afterNavigate((navigation) => {
+        if (!isActive)
+            return;
+        if (isProcessingNavigation) {
+            isProcessingNavigation = false;
+            return;
+        }
+        const url = navigation.to?.url ?? getCurrentLocation();
+        /* v8 ignore next */
+        if (!url)
+            return;
+        syncActorFromRouter(url.pathname, url.search);
+    });
+    const initialLocation = getCurrentLocation();
+    /* v8 ignore next 3 */
+    if (initialLocation) {
+        syncActorFromRouter(initialLocation.pathname, initialLocation.search);
+    }
+    return () => {
+        isActive = false;
+        unwatchRoute();
+    };
+}
+//# sourceMappingURL=connect-router.js.map

package/dist/connect-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-router.js","sourceRoot":"","sources":["../src/connect-router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EACN,kBAAkB,EAClB,wBAAwB,GACxB,MAAM,+BAA+B,CAAC;AAQvC,SAAS,kBAAkB;IAC1B,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC;IACrC,oBAAoB;IACpB,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAE3B,OAAO;QACN,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,MAAM,EAAE,QAAQ,CAAC,MAAM;KACvB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAA6B;IAC1D,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IACpC,IAAI,QAAQ,GAAG,IAAI,CAAC;IACpB,IAAI,sBAAsB,GAAG,KAAK,CAAC;IACnC,IAAI,cAAc,GAAG,wBAAwB,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC;IAElF,MAAM,mBAAmB,GAAG,CAAC,QAAgB,EAAE,MAAc,EAAQ,EAAE;QACtE,IAAI,CAAC,QAAQ,IAAI,sBAAsB;YAAE,OAAO;QAEhD,MAAM,SAAS,GAAG,mBAAmB,CAAC;YACrC,QAAQ;YACR,MAAM;YACN,OAAO,EAAE,CAAC,iBAAiB,EAAE,EAAE;gBAC9B,MAAM,OAAO,GAAG,QAAQ,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;gBAC7D,IAAI,CAAC,OAAO,EAAE,CAAC;oBACd,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;gBACjC,CAAC;gBAED,MAAM,OAAO,GAAG,QAAQ,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;gBACnD,OAAO;oBACN,EAAE,EAAE,OAAO;oBACX,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE;iBACrE,CAAC;YACH,CAAC;SACD,CAAC,CAAC;QAEH,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,QAAQ,KAAK,cAAc;YAAE,OAAO;QAEhE,sBAAsB,GAAG,IAAI,CAAC;QAC9B,cAAc,GAAG,SAAS,CAAC,QAAQ,CAAC;QAEpC,IAAI,CAAC;YACJ,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;gBAAS,CAAC;YACV,sBAAsB,GAAG,KAAK,CAAC;QAChC,CAAC;IACF,CAAC,CAAC;IAEF,MAAM,mBAAmB,GAAG,CAAC,KAAoB,EAAQ,EAAE;QAC1D,oBAAoB;QACpB,IAAI,CAAC,QAAQ,IAAI,sBAAsB,IAAI,CAAC,KAAK;YAAE,OAAO;QAE1D,MAAM,IAAI,GAAG,wBAAwB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACvD,oBAAoB;QACpB,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,cAAc;YAAE,OAAO;QAE7C,MAAM,QAAQ,GAAG,kBAAkB,EAAE,CAAC;QACtC,sBAAsB;QACtB,IAAI,QAAQ,IAAI,QAAQ,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC5C,cAAc,GAAG,IAAI,CAAC;YACtB,OAAO;QACR,CAAC;QAED,sBAAsB,GAAG,IAAI,CAAC;QAC9B,cAAc,GAAG,IAAI,CAAC;QAEtB,KAAK,IAAI,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;aAClD,IAAI,CAAC,GAAG,EAAE;YACV,kEAAkE;YAClE,iFAAiF;YACjF,cAAc,CAAC,GAAG,EAAE;gBACnB,sBAAsB,GAAG,KAAK,CAAC;YAChC,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC;aACD,KAAK,CAAC,GAAG,EAAE;YACX,sBAAsB,GAAG,KAAK,CAAC;QAChC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,MAAM,YAAY,GAAG,WAAW,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,EAAE;QAC9D,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEH,aAAa,CAAC,CAAC,UAAU,EAAE,EAAE;QAC5B,IAAI,CAAC,QAAQ;YAAE,OAAO;QAEtB,IAAI,sBAAsB,EAAE,CAAC;YAC5B,sBAAsB,GAAG,KAAK,CAAC;YAC/B,OAAO;QACR,CAAC;QAED,MAAM,GAAG,GAAG,UAAU,CAAC,EAAE,EAAE,GAAG,IAAI,kBAAkB,EAAE,CAAC;QACvD,oBAAoB;QACpB,IAAI,CAAC,GAAG;YAAE,OAAO;QAEjB,mBAAmB,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;IAEH,MAAM,eAAe,GAAG,kBAAkB,EAAE,CAAC;IAC7C,sBAAsB;IACtB,IAAI,eAAe,EAAE,CAAC;QACrB,mBAAmB,CAAC,eAAe,CAAC,QAAQ,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IACvE,CAAC;IAED,OAAO,GAAG,EAAE;QACX,QAAQ,GAAG,KAAK,CAAC;QACjB,YAAY,EAAE,CAAC;IAChB,CAAC,CAAC;AACH,CAAC"}

package/dist/create-route-map.d.ts

@@ -0,0 +1,4 @@
+import type { AnyStateMachine } from "xstate";
+import { RouteMap } from "./route-map.js";
+export declare function createRouteMap(machine: AnyStateMachine): RouteMap;
+//# sourceMappingURL=create-route-map.d.ts.map

package/dist/create-route-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-route-map.d.ts","sourceRoot":"","sources":["../src/create-route-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CASjE"}

package/dist/create-route-map.js

@@ -0,0 +1,12 @@
+import { extractMachineRoutes, getRoutableRoutes } from "@xmachines/play-router";
+import { RouteMap } from "./route-map.js";
+export function createRouteMap(machine) {
+    const routeTree = extractMachineRoutes(machine);
+    const routes = getRoutableRoutes(routeTree);
+    const mappings = routes.map((node) => ({
+        stateId: node.stateId,
+        path: node.fullPath,
+    }));
+    return new RouteMap(mappings);
+}
+//# sourceMappingURL=create-route-map.js.map

package/dist/create-route-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-route-map.js","sourceRoot":"","sources":["../src/create-route-map.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AACjF,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,UAAU,cAAc,CAAC,OAAwB;IACtD,MAAM,SAAS,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACtC,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,IAAI,EAAE,IAAI,CAAC,QAAQ;KACnB,CAAC,CAAC,CAAC;IAEJ,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC/B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @xmachines/play-sveltekit-router - SvelteKit router adapter for XMachines Play
+ */
+export { RouteMap } from "./route-map.js";
+export { createRouteMap } from "./create-route-map.js";
+export { connectRouter } from "./connect-router.js";
+export type { ConnectRouterOptions } from "./connect-router.js";
+export type { RouteMapping, PlayRouteEvent, RouterBridge, RoutableActor } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * @xmachines/play-sveltekit-router - SvelteKit router adapter for XMachines Play
+ */
+export { RouteMap } from "./route-map.js";
+export { createRouteMap } from "./create-route-map.js";
+export { connectRouter } from "./connect-router.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/route-map.d.ts

@@ -0,0 +1,7 @@
+import { BaseRouteMap } from "@xmachines/play-router";
+/**
+ * SvelteKit route map backed by the shared Play router base class.
+ */
+export declare class RouteMap extends BaseRouteMap {
+}
+//# sourceMappingURL=route-map.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"route-map.d.ts","sourceRoot":"","sources":["../src/route-map.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD;;GAEG;AACH,qBAAa,QAAS,SAAQ,YAAY;CAAG"}

package/dist/route-map.js

@@ -0,0 +1,7 @@
+import { BaseRouteMap } from "@xmachines/play-router";
+/**
+ * SvelteKit route map backed by the shared Play router base class.
+ */
+export class RouteMap extends BaseRouteMap {
+}
+//# sourceMappingURL=route-map.js.map

package/dist/route-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-map.js","sourceRoot":"","sources":["../src/route-map.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,YAAY;CAAG"}

package/dist/types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Type definitions for @xmachines/play-sveltekit-router
+ */
+import type { AbstractActor, Routable } from "@xmachines/play-actor";
+import type { AnyActorLogic } from "xstate";
+export type { PlayRouteEvent, RouterBridge } from "@xmachines/play-router";
+export interface RouteMapping {
+    /** XMachines state ID (for example `#home` or `dashboard.home`). */
+    readonly stateId: string;
+    /** SvelteKit pathname pattern. */
+    readonly path: string;
+}
+export type RoutableActor = AbstractActor<AnyActorLogic> & Routable;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3E,MAAM,WAAW,YAAY;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,aAAa,GAAG,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Type definitions for @xmachines/play-sveltekit-router
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@xmachines/play-sveltekit-router",
+  "version": "1.0.0-beta.24",
+  "description": "SvelteKit router adapter for XMachines Universal Player Architecture",
+  "keywords": [
+    "adapter",
+    "play",
+    "router",
+    "state-machine",
+    "svelte",
+    "sveltekit",
+    "xmachines"
+  ],
+  "license": "MIT",
+  "author": "XMachines Contributors",
+  "repository": {
+    "type": "git",
+    "url": "git@gitlab.com:xmachin-es/xmachines-js.git",
+    "directory": "packages/play-sveltekit-router"
+  },
+  "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"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "lint": "oxlint .",
+    "format": "oxfmt .",
+    "test": "vitest",
+    "clean": "rm -rf dist *.tsbuildinfo coverage .vitest-attachments node_modules/.vite*",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@xmachines/play": "1.0.0-beta.24",
+    "@xmachines/play-actor": "1.0.0-beta.24",
+    "@xmachines/play-router": "1.0.0-beta.24",
+    "@xmachines/play-signals": "1.0.0-beta.24",
+    "@xmachines/play-svelte-router": "1.0.0-beta.24"
+  },
+  "devDependencies": {
+    "@sveltejs/kit": "^2.16.0",
+    "@sveltejs/vite-plugin-svelte": "^7.0.0",
+    "@types/node": "^25.5.0",
+    "@xmachines/shared": "1.0.0-beta.24",
+    "oxfmt": "^0.43.0",
+    "oxlint": "^1.57.0",
+    "svelte": "^5.46.4",
+    "typescript": "^5.9.3 || ^6.0.2",
+    "vitest": "^4.1.2",
+    "xstate": "^5.30.0"
+  },
+  "peerDependencies": {
+    "@sveltejs/kit": "^2.16.0",
+    "svelte": "^5.46.4",
+    "xstate": "^5.30.0"
+  }
+}