@xmachines/play-xstate 3.0.0 → 5.0.0

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import { PlayError } from "@xmachines/play";
+import { PlayError } from "@xmachines/play/errors";
 /**
  * `buildRouteUrl()` throws this error when the context of the actor does not hold a
  * necessary route parameter.
@@ -14,7 +14,7 @@ import { PlayError } from "@xmachines/play";
  *
  * @example
  * ```typescript
- * import { buildRouteUrl } from "@xmachines/play-xstate";
+ * import { buildRouteUrl } from "@xmachines/play-xstate/routing";
  * import { MissingRouteParamError } from "@xmachines/play-xstate/errors";
  *
  * try {
@@ -36,21 +36,42 @@ export declare class MissingRouteParamError extends PlayError {
     constructor(param: string, template: string);
 }
 /**
- * @deprecated Nothing throws this error now. `buildRouteUrl` reads an absent `query`
- * field as `query: {}`. The generated `play.route` transitions assign `query` on
- * every navigation, and the loss that this error guarded against therefore cannot
- * happen through the route derivation. A machine that handles `play.route` itself
- * and wants the query must assign `event.query` to its context itself. This class
- * stays in the exports, so that an `instanceof` handler that exists now still
- * compiles. Remove such a handler when you have the time.
- *
- * `buildRouteUrl()` threw this error before, when the context had a `params` field,
- * which means a context that knows the routing, but no `query` field.
- *
- * **Error code:** `PLAY_XSTATE_MISSING_QUERY_CONTEXT`
+ * `buildRouteUrl()` throws this error when a route parameter carries a value that no path
+ * can hold, so the template matches the built URL back never.
+ *
+ * A dot segment is that value. A URL parser resolves `.` and `..` BEFORE it decodes the
+ * percent escapes, and it counts `%2e` as the dot, so every encoding of them resolves
+ * away: `/files/..` becomes `/`. The actor would hold the route `/files/..` while the
+ * address bar shows `/`, and the two stay out of step for the rest of the session.
+ *
+ * Give the param a value that names a segment. Machine state that can carry a path from a
+ * user belongs behind a check of its own, in the same way that a base path checks the
+ * values of its `:param` segments.
+ *
+ * **Error code:** `PLAY_XSTATE_ROUTE_PARAM_INVALID`
+ *
+ * @example
+ * ```typescript
+ * import { buildRouteUrl } from "@xmachines/play-xstate/routing";
+ * import { InvalidRouteParamError } from "@xmachines/play-xstate/errors";
+ *
+ * try {
+ *   buildRouteUrl("/files/:name", { params: { name: ".." }, query: {} });
+ * } catch (err) {
+ *   if (err instanceof InvalidRouteParamError) {
+ *     console.error(`"${err.value}" cannot stand in "${err.param}"`);
+ *   }
+ * }
+ * ```
  */
-export declare class MissingQueryContextError extends PlayError {
-    constructor();
+export declare class InvalidRouteParamError extends PlayError {
+    /** The name of the route parameter that carries the value, for example `"name"`. */
+    readonly param: string;
+    /** The value that no path can hold, for example `".."`. */
+    readonly value: string;
+    /** The route template that declares the parameter, for example `"/files/:name"`. */
+    readonly template: string;
+    constructor(param: string, value: string, template: string);
 }
 /**
  * `formatPlayRouteTransitions()` throws this error when a state node declares a
@@ -112,15 +133,35 @@ export declare class InvalidRouteMetadataError extends PlayError {
     constructor(route: unknown, source?: string);
 }
 /**
- * `composeGuards()` and `composeGuardsOr()` throw this error for an empty array of
- * guards. A composition of zero guards has no meaning.
+ * `formatPlayRouteTransitions()` throws this error for a `meta.route` object whose
+ * `handler` field holds a value that the routing layer does not know.
+ *
+ * The field decides WHERE the generated `play.route` transition sits, and each value
+ * produces a different reachability. `"local"` in particular makes a state reachable
+ * only while its parent is active. A typo such as `"locale"` would therefore fall back
+ * to a placement that the author did not ask for, and the route would behave correctly
+ * in the test that the author wrote and wrongly everywhere else. The error refuses the
+ * value instead.
+ *
+ * **Error code:** `PLAY_XSTATE_INVALID_ROUTE_HANDLER`
+ *
+ * @example
+ * ```typescript
+ * import { InvalidRouteHandlerError } from "@xmachines/play-xstate/errors";
  *
- * **Error code:** `PLAY_XSTATE_EMPTY_GUARD_ARRAY`
+ * try {
+ *   formatPlayRouteTransitions(config);
+ * } catch (error) {
+ *   if (error instanceof InvalidRouteHandlerError) {
+ *     console.error(error.handler); // the value that the config declared
+ *   }
+ * }
+ * ```
  */
-export declare class EmptyGuardArrayError extends PlayError {
-    /** The combinator of the call with the empty array: `"and"` or `"or"`. */
-    readonly combinator: "and" | "or";
-    constructor(combinator: "and" | "or");
+export declare class InvalidRouteHandlerError extends PlayError {
+    /** The value that the config declared, as a string, for the debug work. */
+    readonly handler: string;
+    constructor(handler: unknown, source?: string);
 }
 /**
  * `PlayerActor.send()` throws this error when the event argument is not a plain

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAsB5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,sBAAuB,SAAQ,SAAS;IACpD,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU3C;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;;CAWtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAW3C;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;;CASjD;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;IACvD,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,KAAK,EAAE,OAAO,EAAE,MAAM,SAAgB;CAUlD;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAClD,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;gBAEtB,UAAU,EAAE,KAAK,GAAG,IAAI;CASpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC/C,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,MAAM,EAAE,OAAO;CAS3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;gBACzC,KAAK,EAAE,OAAO;CAS1B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAsBnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,sBAAuB,SAAQ,SAAS;IACpD,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,sBAAuB,SAAQ,SAAS;IACpD,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAW1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAW3C;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;;CASjD;AAqBD;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;IACvD,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,KAAK,EAAE,OAAO,EAAE,MAAM,SAAgB;CAUlD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;IACtD,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,OAAO,EAAE,MAAM,SAA+B;CAUnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC/C,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,MAAM,EAAE,OAAO;CAS3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;gBACzC,KAAK,EAAE,OAAO;CAS1B"}

package/dist/errors.js

@@ -1,4 +1,4 @@
-import { PlayError } from "@xmachines/play";
+import { PlayError } from "@xmachines/play/errors";
 /**
  * Converts a value from a throw into a string, and it trusts that value not:
  * `String()` itself throws for an object with a null prototype, and also for a value
@@ -35,7 +35,7 @@ const safeString = (value) => {
  *
  * @example
  * ```typescript
- * import { buildRouteUrl } from "@xmachines/play-xstate";
+ * import { buildRouteUrl } from "@xmachines/play-xstate/routing";
  * import { MissingRouteParamError } from "@xmachines/play-xstate/errors";
  *
  * try {
@@ -62,25 +62,47 @@ export class MissingRouteParamError extends PlayError {
     }
 }
 /**
- * @deprecated Nothing throws this error now. `buildRouteUrl` reads an absent `query`
- * field as `query: {}`. The generated `play.route` transitions assign `query` on
- * every navigation, and the loss that this error guarded against therefore cannot
- * happen through the route derivation. A machine that handles `play.route` itself
- * and wants the query must assign `event.query` to its context itself. This class
- * stays in the exports, so that an `instanceof` handler that exists now still
- * compiles. Remove such a handler when you have the time.
- *
- * `buildRouteUrl()` threw this error before, when the context had a `params` field,
- * which means a context that knows the routing, but no `query` field.
- *
- * **Error code:** `PLAY_XSTATE_MISSING_QUERY_CONTEXT`
+ * `buildRouteUrl()` throws this error when a route parameter carries a value that no path
+ * can hold, so the template matches the built URL back never.
+ *
+ * A dot segment is that value. A URL parser resolves `.` and `..` BEFORE it decodes the
+ * percent escapes, and it counts `%2e` as the dot, so every encoding of them resolves
+ * away: `/files/..` becomes `/`. The actor would hold the route `/files/..` while the
+ * address bar shows `/`, and the two stay out of step for the rest of the session.
+ *
+ * Give the param a value that names a segment. Machine state that can carry a path from a
+ * user belongs behind a check of its own, in the same way that a base path checks the
+ * values of its `:param` segments.
+ *
+ * **Error code:** `PLAY_XSTATE_ROUTE_PARAM_INVALID`
+ *
+ * @example
+ * ```typescript
+ * import { buildRouteUrl } from "@xmachines/play-xstate/routing";
+ * import { InvalidRouteParamError } from "@xmachines/play-xstate/errors";
+ *
+ * try {
+ *   buildRouteUrl("/files/:name", { params: { name: ".." }, query: {} });
+ * } catch (err) {
+ *   if (err instanceof InvalidRouteParamError) {
+ *     console.error(`"${err.value}" cannot stand in "${err.param}"`);
+ *   }
+ * }
+ * ```
  */
-export class MissingQueryContextError extends PlayError {
-    constructor() {
-        super("buildRouteUrl", "PLAY_XSTATE_MISSING_QUERY_CONTEXT", "buildRouteUrl() received a context without a 'query' field. " +
-            "Declare 'query: Record<string, string>' in the machine context type and " +
-            "initialise it to {} so query parameters from play.route events are not silently dropped.");
-        this.name = "MissingQueryContextError";
+export class InvalidRouteParamError extends PlayError {
+    /** The name of the route parameter that carries the value, for example `"name"`. */
+    param;
+    /** The value that no path can hold, for example `".."`. */
+    value;
+    /** The route template that declares the parameter, for example `"/files/:name"`. */
+    template;
+    constructor(param, value, template) {
+        super("buildRouteUrl", "PLAY_XSTATE_ROUTE_PARAM_INVALID", `Route parameter '${param}' of template '${template}' carries the value '${value}', which resolves away in a URL.`);
+        this.name = "InvalidRouteParamError";
+        this.param = param;
+        this.value = value;
+        this.template = template;
     }
 }
 /**
@@ -140,6 +162,25 @@ export class InvalidMachineError extends PlayError {
         this.name = "InvalidMachineError";
     }
 }
+/**
+ * Describes an unknown value for the message of an error, and throws nothing itself.
+ *
+ * `JSON.stringify` alone is not enough for a value that arrives from the config of a
+ * user. It returns the VALUE `undefined` for a function, for a symbol, and for
+ * `undefined`, which puts the text "undefined" in a field that is declared `string`.
+ * It also THROWS a `TypeError` for a circular object, and an error constructor that
+ * throws hides the error that it was built to report.
+ *
+ * The fallback names the type instead, for example `[function]`.
+ */
+function describeValue(value) {
+    try {
+        return JSON.stringify(value) ?? `[${typeof value}]`;
+    }
+    catch {
+        return `[${typeof value}]`;
+    }
+}
 /**
  * `normalizeRoute()` throws this error when the `meta.route` value of a state is not
  * a string and not an object with a `path` property.
@@ -150,25 +191,46 @@ export class InvalidRouteMetadataError extends PlayError {
     /** The invalid route value, as a string, for the debug work. */
     detail;
     constructor(route, source = "deriveRoute") {
-        const detail = JSON.stringify(route);
+        const detail = describeValue(route);
         super(source, "PLAY_XSTATE_INVALID_ROUTE_METADATA", `Invalid route metadata: ${detail}. Expected string or { path: string }`);
         this.name = "InvalidRouteMetadataError";
         this.detail = detail;
     }
 }
 /**
- * `composeGuards()` and `composeGuardsOr()` throw this error for an empty array of
- * guards. A composition of zero guards has no meaning.
+ * `formatPlayRouteTransitions()` throws this error for a `meta.route` object whose
+ * `handler` field holds a value that the routing layer does not know.
+ *
+ * The field decides WHERE the generated `play.route` transition sits, and each value
+ * produces a different reachability. `"local"` in particular makes a state reachable
+ * only while its parent is active. A typo such as `"locale"` would therefore fall back
+ * to a placement that the author did not ask for, and the route would behave correctly
+ * in the test that the author wrote and wrongly everywhere else. The error refuses the
+ * value instead.
  *
- * **Error code:** `PLAY_XSTATE_EMPTY_GUARD_ARRAY`
+ * **Error code:** `PLAY_XSTATE_INVALID_ROUTE_HANDLER`
+ *
+ * @example
+ * ```typescript
+ * import { InvalidRouteHandlerError } from "@xmachines/play-xstate/errors";
+ *
+ * try {
+ *   formatPlayRouteTransitions(config);
+ * } catch (error) {
+ *   if (error instanceof InvalidRouteHandlerError) {
+ *     console.error(error.handler); // the value that the config declared
+ *   }
+ * }
+ * ```
  */
-export class EmptyGuardArrayError extends PlayError {
-    /** The combinator of the call with the empty array: `"and"` or `"or"`. */
-    combinator;
-    constructor(combinator) {
-        super(combinator === "and" ? "composeGuards" : "composeGuardsOr", "PLAY_XSTATE_EMPTY_GUARD_ARRAY", `${combinator === "and" ? "composeGuards" : "composeGuardsOr"} requires at least one guard`);
-        this.name = "EmptyGuardArrayError";
-        this.combinator = combinator;
+export class InvalidRouteHandlerError extends PlayError {
+    /** The value that the config declared, as a string, for the debug work. */
+    handler;
+    constructor(handler, source = "formatPlayRouteTransitions") {
+        const detail = describeValue(handler);
+        super(source, "PLAY_XSTATE_INVALID_ROUTE_HANDLER", `Invalid route handler: ${detail}. Expected "root", "local", or "both"`);
+        this.name = "InvalidRouteHandlerError";
+        this.handler = detail;
     }
 }
 /**

package/dist/errors.js.map

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

package/dist/index.d.ts

@@ -2,21 +2,19 @@
  * @xmachines/play-xstate - the XState v5 adapter of the Play Architecture
  *
  * This package gives you the definePlayer() API. That function binds an XState state
- * machine to the actor base, with the signal lifecycle and the DevTools
+ * machine to the actor base, with the atom lifecycle and the DevTools
  * integration.
  *
  * The Play RFC gives this package as the adapter of the logic layer. It converts a
- * declarative machine definition into a live actor with a signal-driven
+ * declarative machine definition into a live actor with an atom-driven
  * reactivity.
  *
  * @packageDocumentation
  */
 export { definePlayer } from "./define-player.js";
 export { PlayerActor } from "./player-actor.js";
+export { compose } from "./capabilities.js";
+export type { Capability, PlayerConstructor } from "./capabilities.js";
 export type { PlayerConfig, PlayerOptions, PlayerFactory, PlayerFactoryResumeOptions, } from "./types.js";
-export { composeGuards, composeGuardsOr, negateGuard, hasContext, eventMatches, contextFieldMatches, } from "./guards/index.js";
-export type { Guard, GuardArray, ComposedGuard } from "./guards/index.js";
-export { deriveRoute, isAbsoluteRoute, buildRouteUrl, formatPlayRouteTransitions, } from "./routing/index.js";
-export type { RouteMachineConfig, RouteStateNode, RouteContext, RouteObject, RouteMetadata, } from "./routing/index.js";
 export { DISPOSE } from "@xmachines/play";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EACX,YAAY,EACZ,aAAa,EACb,aAAa,EACb,0BAA0B,GAC1B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACN,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,YAAY,EACZ,mBAAmB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAG1E,OAAO,EACN,WAAW,EACX,eAAe,EACf,aAAa,EACb,0BAA0B,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACX,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,WAAW,EACX,aAAa,GACb,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIhD,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACvE,YAAY,EACX,YAAY,EACZ,aAAa,EACb,aAAa,EACb,0BAA0B,GAC1B,MAAM,YAAY,CAAC;AAWpB,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -2,21 +2,26 @@
  * @xmachines/play-xstate - the XState v5 adapter of the Play Architecture
  *
  * This package gives you the definePlayer() API. That function binds an XState state
- * machine to the actor base, with the signal lifecycle and the DevTools
+ * machine to the actor base, with the atom lifecycle and the DevTools
  * integration.
  *
  * The Play RFC gives this package as the adapter of the logic layer. It converts a
- * declarative machine definition into a live actor with a signal-driven
+ * declarative machine definition into a live actor with an atom-driven
  * reactivity.
  *
  * @packageDocumentation
  */
 export { definePlayer } from "./define-player.js";
 export { PlayerActor } from "./player-actor.js";
-// The guard utilities
-export { composeGuards, composeGuardsOr, negateGuard, hasContext, eventMatches, contextFieldMatches, } from "./guards/index.js";
-// The routing utilities
-export { deriveRoute, isAbsoluteRoute, buildRouteUrl, formatPlayRouteTransitions, } from "./routing/index.js";
+// The composition of the capabilities. Each capability itself lives behind its own entry
+// point — `@xmachines/play-xstate/routing` and `@xmachines/play-xstate/view` — so this
+// module imports neither, and an application loads only what it composes.
+export { compose } from "./capabilities.js";
+// The routing utilities live behind `@xmachines/play-xstate/routing`, with the mixin
+// that needs them: `deriveRoute`, `isAbsoluteRoute`, `buildRouteUrl`,
+// `formatPlayRouteTransitions`, and the route types. Each one names
+// `@xmachines/play-router` in its `.d.ts`, and that package is an OPTIONAL peer. This
+// entry therefore names no capability package, exactly as the view half does.
 // The release protocol of @xmachines/play. This package's own published `.d.ts` names
 // exactly these, so a consumer reads them from here and needs no second manifest
 // entry. It names `asCleanup` nowhere: a consumer of this package RECEIVES a

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQhD,sBAAsB;AACtB,OAAO,EACN,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,YAAY,EACZ,mBAAmB,GACnB,MAAM,mBAAmB,CAAC;AAG3B,wBAAwB;AACxB,OAAO,EACN,WAAW,EACX,eAAe,EACf,aAAa,EACb,0BAA0B,GAC1B,MAAM,oBAAoB,CAAC;AAQ5B,sFAAsF;AACtF,iFAAiF;AACjF,6EAA6E;AAC7E,4DAA4D;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,yFAAyF;AACzF,uFAAuF;AACvF,0EAA0E;AAC1E,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAS5C,qFAAqF;AACrF,sEAAsE;AACtE,oEAAoE;AACpE,sFAAsF;AACtF,8EAA8E;AAC9E,sFAAsF;AACtF,iFAAiF;AACjF,6EAA6E;AAC7E,4DAA4D;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC"}