@xmachines/play-xstate 2.0.0 → 2.1.0

package/dist/view/derive-current-view.js

@@ -1,11 +1,13 @@
 import { composePlayState, toAtomState } from "@xmachines/play-actor";
 import { activeStateMeta } from "../routing/index.js";
 /**
- * Once-per-spec migration warning for the removed 1.x `contextProps` field.
- * Hand-written meta.view objects bypass `typedSpec`, so a spec still carrying
- * the field compiles clean — but its meaning inverted (an allowlist, or an
- * empty filter projecting nothing, is now the whole context). Keyed on the
- * static meta.view object so the warning fires once, not per snapshot.
+ * The migration warning of the `contextProps` field, which 1.x removed. The code
+ * writes it one time for each spec. A meta.view object from a person passes around
+ * `typedSpec`, and a spec with the field therefore compiles without an error. But
+ * the meaning of the field inverted: it was an allowlist, or an empty filter that
+ * projected nothing, and the whole context is the value now. The key is the static
+ * meta.view object. Therefore the warning appears one time, and not for each
+ * snapshot.
  */
 const warnedContextProps = new WeakSet();
 const warnRemovedContextProps = (viewMeta) => {
@@ -16,12 +18,12 @@ const warnRemovedContextProps = (viewMeta) => {
         "is always projected under /context. Delete the field — it no longer filters anything.");
 };
 const resolveViewMeta = (meta) => {
-    // Iterate last-to-first: snapshot.getMeta() orders keys ancestors-first, so
-    // scanning from the end makes the deepest active state's meta.view win over
-    // an ancestor's instead of being shadowed by it.
+    // Walk from the last entry to the first: snapshot.getMeta() puts the keys of the
+    // ancestors first. A scan from the end therefore lets the meta.view of the deepest
+    // active state win, and an ancestor hides it not.
     const entries = Object.entries(meta);
     for (let i = entries.length - 1; i >= 0; i--) {
-        // Loop-bounded array index, not user-controlled property access.
+        // The array index has the bound of the loop. No user controls this property access.
         const [key, stateMeta] = entries[i]; // nosemgrep: gitlab.eslint.detect-object-injection
         const maybeView = stateMeta && typeof stateMeta === "object"
             ? stateMeta.view
@@ -36,54 +38,56 @@ const resolveViewMeta = (meta) => {
     return null;
 };
 /**
- * Derive the actor's current view from state metadata.
+ * Derives the current view of the actor from the state metadata.
  *
- * Always returns a **fresh** `PlaySpec` object so a genuine view change is never
- * suppressed by `Signal.State`'s `Object.is` equality check. Whether that fresh
- * object is actually emitted is decided by `PlayerActor.validateAndCacheView`,
- * which compares against the last emitted spec (reusing the composed `state`
- * reference when the projection is value-unchanged) and skips emission when the
- * rendered view is unchanged — preventing downstream providers from remounting
- * the UI on every event.
+ * The function always returns a **fresh** `PlaySpec` object. The `Object.is`
+ * equality test of `Signal.State` therefore stops no real change of the view.
+ * `PlayerActor.validateAndCacheView` decides if the actor emits that fresh object:
+ * it compares the object with the last spec of an emission, it reuses the reference
+ * of the composed `state` field when the value of the projection did not change, and
+ * it emits nothing when the view on the screen is the same. A provider below the
+ * actor therefore mounts the UI again not on every event.
  *
- * ### Context projection
+ * ### The context projection
  *
- * The machine's context is projected into the derived spec's `state` under the
- * read-only `/context` subtree: `state: { ...meta.view.state, context: slice }`.
- * The emitted spec is therefore **self-consistent** — its `state` honestly
- * describes the store contents — so `repeat.statePath: "/context/tasks"`,
- * `visible: { $state: "/context/…" }`, and `{ $state: "/context/…" }` props all
- * resolve through the ordinary state grammar, and tools like `validateSpec`
- * pass on derived views with no special-casing (validate the derived view, not
- * the raw `meta.view`).
+ * The function projects the context of the machine into the `state` field of the
+ * derived spec, under the read-only `/context` subtree:
+ * `state: { ...meta.view.state, context: slice }`. The spec of the emission is
+ * therefore **consistent with itself**, and its `state` field describes the contents
+ * of the store correctly. `repeat.statePath: "/context/tasks"`,
+ * `visible: { $state: "/context/…" }`, and a `{ $state: "/context/…" }` prop all
+ * resolve through the ordinary state grammar. A tool such as `validateSpec` also
+ * passes on a derived view, with no special case. Validate the derived view, and not
+ * the raw `meta.view`.
  *
- * The whole context is always projected; the authored `meta.view` object is
- * never mutated.
+ * The store always holds the complete context. The function changes the authored
+ * `meta.view` object never.
  *
- * ### viewKey
+ * ### The viewKey
  *
- * The derived spec carries `viewKey` — the meta record key (state node id) of
- * the entry this derivation actually selected. Providers key their store
- * lifecycle on it: changed → reseed, unchanged → refresh `/context` in place.
- * It is taken from the selected entry rather than "the active state id"
- * because for parallel machines the walked branch and the flat `getMeta()`
- * fallback can select a view from a different region than the branch leaf.
+ * The derived spec carries a `viewKey` field. Its value is the key of the meta
+ * record, which is the id of the state node, of the entry that this derivation
+ * selected. A provider uses it as the key of its store lifecycle: a new key seeds
+ * the store again, and the same key refreshes `/context` in place. The value comes
+ * from the selected entry, and not from "the id of the active state", because for a
+ * parallel machine the branch of the walk and the flat `getMeta()` fallback can
+ * select a view of a different region than the leaf of the branch.
  *
- * @param snapshot - Current XState machine snapshot.
- * @returns Derived `PlaySpec`, or `null` if the current state has no view metadata.
+ * @param snapshot - The current snapshot of the XState machine.
+ * @returns The derived `PlaySpec`, or `null` when the current state has no view metadata.
  */
 export const deriveCurrentView = (snapshot) => {
-    // Follow the SAME single active branch the route derivation walks, so that
-    // for a parallel machine the rendered view belongs to the region the URL
-    // points at whenever that region declares one.
+    // Follow the SAME single active branch as the route derivation. Therefore the view
+    // on the screen of a parallel machine belongs to the region of the URL, when that
+    // region declares a view.
     const meta = activeStateMeta(snapshot);
     if (!meta) {
         return null;
     }
-    // A parallel machine may keep routes and views in DIFFERENT regions (one
-    // region owns navigation, another owns the shell). When the walked branch
-    // declares no view, scan the flat record of every active region — deepest
-    // entry wins — before concluding there is no view at all.
+    // A parallel machine can hold its routes and its views in DIFFERENT regions: one
+    // region owns the navigation, and another region owns the shell. When the branch of
+    // the walk declares no view, scan the flat record of every active region, where the
+    // deepest entry wins, before the conclusion that no view is present.
     let resolved = resolveViewMeta(meta);
     if (!resolved) {
         const flatMeta = snapshot.getMeta();
@@ -98,9 +102,9 @@ export const deriveCurrentView = (snapshot) => {
     if ("contextProps" in viewMeta) {
         warnRemovedContextProps(viewMeta);
     }
-    // Project the whole context under /context. composePlayState skips the
-    // projection (authored state wins, with a dev warning) when spec.state
-    // already declares a top-level "context" key.
+    // Project the complete context under /context. composePlayState skips the
+    // projection, the authored state wins, and the code writes a warning in development,
+    // when spec.state declares a top-level "context" key already.
     const slice = snapshot.context !== null && typeof snapshot.context === "object"
         ? snapshot.context
         : undefined;

package/dist/view/derive-current-view.js.map

@@ -1 +1 @@
-{"version":3,"file":"derive-current-view.js","sourceRoot":"","sources":["../../src/view/derive-current-view.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"derive-current-view.js","sourceRoot":"","sources":["../../src/view/derive-current-view.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAiB,MAAM,uBAAuB,CAAC;AAErF,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAStD;;;;;;;;GAQG;AACH,MAAM,kBAAkB,GAAG,IAAI,OAAO,EAAU,CAAC;AACjD,MAAM,uBAAuB,GAAG,CAAC,QAAgB,EAAQ,EAAE;IAC1D,IAAI,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC;QAAE,OAAO;IAC7C,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACjC,OAAO,CAAC,IAAI,CACX,mFAAmF;QAClF,uFAAuF,CACxF,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,IAA6B,EAA2B,EAAE;IAClF,iFAAiF;IACjF,mFAAmF;IACnF,kDAAkD;IAClD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,oFAAoF;QACpF,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,GAAG,OAAO,CAAC,CAAC,CAAsB,CAAC,CAAC,mDAAmD;QAC7G,MAAM,SAAS,GACd,SAAS,IAAI,OAAO,SAAS,KAAK,QAAQ;YACzC,CAAC,CAAE,SAAgC,CAAC,IAAI;YACxC,CAAC,CAAC,SAAS,CAAC;QAEd,IACC,SAAS;YACT,OAAO,SAAS,KAAK,QAAQ;YAC7B,MAAM,IAAK,SAAoB;YAC/B,UAAU,IAAK,SAAoB,EAClC,CAAC;YACF,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,SAAqB,EAAE,CAAC;QAC7C,CAAC;IACF,CAAC;IAED,OAAO,IAAI,CAAC;AACb,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,QAA4B,EAAmB,EAAE;IAClF,mFAAmF;IACnF,kFAAkF;IAClF,0BAA0B;IAC1B,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACb,CAAC;IAED,iFAAiF;IACjF,oFAAoF;IACpF,oFAAoF;IACpF,qEAAqE;IACrE,IAAI,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC9C,QAAQ,GAAG,eAAe,CAAC,QAAmC,CAAC,CAAC;QACjE,CAAC;IACF,CAAC;IACD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACb,CAAC;IACD,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAAC;IAElD,IAAI,cAAc,IAAI,QAAQ,EAAE,CAAC;QAChC,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED,0EAA0E;IAC1E,qFAAqF;IACrF,8DAA8D;IAC9D,MAAM,KAAK,GACV,QAAQ,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ;QAChE,CAAC,CAAE,QAAQ,CAAC,OAAmC;QAC/C,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,aAAa,GAAG,QAAQ,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7F,MAAM,KAAK,GAAG,gBAAgB,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IAErD,OAAO;QACN,GAAG,QAAQ;QACX,OAAO;QACP,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC;KACrC,CAAC;AACH,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-xstate",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "XState v5 adapter for Play Architecture",
   "keywords": [
     "actor-model",
@@ -44,19 +44,20 @@
     "clean": "rm -rf dist *.tsbuildinfo coverage node_modules/.svelte2tsx-* node_modules/.vite*",
     "lint": "oxlint .",
     "format": "oxfmt .",
-    "test": "vitest"
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xmachines/play": "2.0.0",
-    "@xmachines/play-actor": "2.0.0",
-    "@xmachines/play-signals": "2.0.0",
+    "@xmachines/play": "2.1.0",
+    "@xmachines/play-actor": "2.1.0",
+    "@xmachines/play-signals": "2.1.0",
     "dequal": "^2.0.3"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
     "@types/node": "^26.2.0",
     "@xmachines/json-render-core": "^0.20.0-xm.2",
-    "@xmachines/play-router": "2.0.0",
+    "@xmachines/play-router": "2.1.0",
     "oxfmt": "^0.64.0",
     "oxlint": "^1.79.0",
     "typescript": "^5.9.3 || ^6.0.3",