@inglorious/store 11.2.0 → 12.0.0

package/README.md

@@ -400,6 +400,9 @@ The practical use is a world whose rules change with its state — a keyboard wh
 mean one thing on a menu and another in play:
 
 ```javascript
+import { fsm } from "@inglorious/store/fsm"
+import { scenes } from "@inglorious/store/scenes"
+
 const types = {
   Keyboard: { keyDown: (entity, key) => report(key) },
   Game: [
@@ -730,7 +733,7 @@ Inglorious Store now provides utilities to **gradually migrate from RTK slices a
 ### Converting Async Thunks
 
 ```javascript
-import { convertAsyncThunk } from "@inglorious/store/rtk"
+import { convertAsyncThunk } from "@inglorious/store/migration/rtk"
 
 const fetchTodos = async (userId) => {
   const res = await fetch(`/api/users/${userId}/todos`)
@@ -765,7 +768,7 @@ const todoList = {
 ### Converting Slices
 
 ```javascript
-import { convertSlice } from "@inglorious/store/rtk"
+import { convertSlice } from "@inglorious/store/migration/rtk"
 
 const todoListType = convertSlice(todosSlice, {
   asyncThunks: {
@@ -806,7 +809,7 @@ dispatch({ type: "todos/addTodo", payload: "Buy milk" })
 ### Migration Guide
 
 ```javascript
-import { createMigrationGuide } from "@inglorious/store/rtk"
+import { createMigrationGuide } from "@inglorious/store/migration/rtk"
 
 const guide = createMigrationGuide(todosSlice)
 console.log(guide)
@@ -968,7 +971,108 @@ const withLoading = (type) => ({
 const form = [resettable, validated, withLoading]
 ```
 
-When multiple behaviors define the same event, they all run in order. This allows you to build middleware-like patterns: validation, logging, error handling, loading states, etc.
+When multiple behaviors define the same event, the later one replaces the earlier: a type has one handler per event. That is why a wrapper like `validated` receives the type built so far and calls `type.submit?.(...)` itself, which is how you build middleware-like patterns: validation, logging, error handling, loading states, etc.
+
+### 🚦 State Machines
+
+Some entities answer the same event differently depending on the state they are in: a door
+opens when it is closed and does nothing when it is locked. `fsm()` turns a type into a
+finite state machine in the manner of the OOP State pattern, where each state says what it
+answers and the entity's `state` field says which state is in charge:
+
+```javascript
+import { fsm } from "@inglorious/store/fsm"
+
+const types = {
+  Door: [
+    {
+      // What every state does, unless a state says otherwise
+      knock(entity) {
+        entity.knocks++
+      },
+    },
+    fsm({
+      closed: {
+        open(entity) {
+          entity.state = "open"
+        },
+        lock(entity) {
+          entity.state = "locked"
+        },
+      },
+      open: {
+        close(entity) {
+          entity.state = "closed"
+        },
+      },
+      locked: {
+        // Takes over knock while locked
+        knock(entity, _, api) {
+          api.notify("bark")
+        },
+        unlock(entity) {
+          entity.state = "closed"
+        },
+      },
+    }),
+  ],
+}
+
+const entities = { door: { type: "Door", state: "closed", knocks: 0 } }
+```
+
+- A state's handler **replaces** the type's handler for the same event, so the type's
+  handler is the default and a state takes it over by naming the event. An event that
+  neither the current state nor the type answers is ignored.
+- A handler moves the entity by assigning `entity.state`. An entity with no `state` starts
+  in `"default"`.
+- When a handler has actually moved the entity, `fsm` broadcasts
+  `stateChange` with `{ entityId, from, to }`. It is broadcast rather than addressed to the
+  entity, because what wants to hear it is usually something else, so a listener checks
+  `entityId`.
+
+Typical uses: request and connection status, wizards, editors that are viewing, editing or
+saving, media players, drag and drop, and the screens of a game.
+
+#### Scenes
+
+`scenes()` is the usual partner of `fsm()`: the machine says when it moves, and `scenes()`
+says which entities stand in each state. On `create` and on its own `stateChange` it `add`s
+what the new state has, `remove`s what only the old one had, and `patch`es what both have
+but configure differently, comparing entities by `id`:
+
+```javascript
+import { fsm } from "@inglorious/store/fsm"
+import { scenes } from "@inglorious/store/scenes"
+
+const types = {
+  Wizard: [
+    scenes({
+      account: () => [{ id: "accountForm", type: "AccountForm" }],
+      billing: (wizard) => [
+        { id: "billingForm", type: "BillingForm", plan: wizard.plan },
+      ],
+    }),
+    fsm({
+      account: {
+        next(entity) {
+          entity.state = "billing"
+        },
+      },
+    }),
+  ],
+}
+
+const entities = { wizard: { type: "Wizard", state: "account", plan: "pro" } }
+```
+
+The entity running the machine keeps what it has up in `scene`.
+
+The name comes from games, where each screen is a scene, but nothing about it is game-specific.
+In a web app it gives entities a lifetime tied to a state: a page's forms and lists exist only
+while you are on it (their `create` and `destroy` can open and close subscriptions), each wizard
+step has its own form, and a logged-out app has a `loginForm` that a logged-in one does not —
+while anything both states share, like a header or a cart, survives the move untouched.
 
 ### ⏱️ Batched Mode
 
@@ -1135,7 +1239,7 @@ const store = createStore({
   systems, // Array (optional): global state handlers
   autoCreateEntities, // Boolean (optional): false (default) or true
   updateMode, // String (optional): 'auto' (default) or 'manual'
-  updateStrategy, // String (optional): 'structural-sharing' (default) or 'full-clone'
+  updateStrategy, // String (optional): 'structural-sharing' (default) or 'copy-on-dispatch'
 })
 ```
 
@@ -1154,7 +1258,7 @@ const store = createStore({
   - `'manual'` - Manual control via `api.update()`
 - **`updateStrategy`** (optional) - Controls how the state is copied before queued events are applied:
   - `'structural-sharing'` (default) - Only the entities that actually changed are copied
-  - `'full-clone'` - The whole state is deep-cloned and updated without a proxy
+  - `'copy-on-dispatch'` - Each entity is deep-copied as it is handed out, and updated without a proxy
 
 #### Update Strategy
 
@@ -1167,10 +1271,26 @@ get copied. Untouched entities keep their previous object reference, which makes
 reference-equality change detection nearly free. This is what you want for UI stores, where a
 handful of entities change per interaction.
 
-**`'full-clone'`** deep-clones the entire state with `structuredClone` and applies events directly to
-the copy, with no proxy involved. Every update costs time proportional to the total state size,
-but there's no per-entity proxy overhead, so it scales much better when thousands of entities
-change every frame — the typical case for a game simulation.
+**`'copy-on-dispatch'`** deep-copies an entity the first time it is handed to one of its handlers, or read
+by a system, and applies events directly to the copy, with no proxy involved. Entities that nothing
+touches during an update are not copied and keep their previous reference. Writing to a copy costs
+nothing however often it happens, so it scales much better when thousands of entities change every
+frame — the typical case for a game simulation.
+
+Systems receive every entity at once, so each entity a system reads through its first argument is
+copied in case it is written to. A system that only needs to know how things stood should read
+them from `api.getEntities()` and go through its first argument only for what it writes:
+
+```javascript
+const readouts = {
+  update(entities, dt, api) {
+    const current = api.getEntities() // read without copying
+    const count = Object.keys(current).length
+
+    entities.readout.value = `${count} entities` // copies only the readout
+  },
+}
+```
 
 ```javascript
 // A UI store: few entities change, reference equality matters
@@ -1181,7 +1301,11 @@ const store = createStore({
 })
 
 // A game simulation: thousands of entities change every frame
-const store = createStore({ types, entities, updateStrategy: "full-clone" })
+const store = createStore({
+  types,
+  entities,
+  updateStrategy: "copy-on-dispatch",
+})
 ```
 
 #### State swapping
@@ -1207,23 +1331,23 @@ const types = {
 }
 ```
 
-**Caveats for `'full-clone'`:**
+**Caveats for `'copy-on-dispatch'`:**
 
-- Every value in the state must be [structured-cloneable](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm).
-  Functions, DOM nodes, and class instances with non-cloneable internals throw a
-  `DataCloneError`. Keep such values in module scope or in a closure inside a behavior factory
+- Plain objects, arrays, vectors and primitives are copied directly. Anything else must be
+  [structured-cloneable](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm):
+  DOM nodes and class instances with non-cloneable internals throw a `DataCloneError`. Keep such values in module scope or in a closure inside a behavior factory
   (as the `images()` and `audio()` engine behaviors do) rather than in the state.
 - The state is not frozen, even in `devMode`.
 - Writing to an entity obtained from `api.getEntity()` during an update mutates the _previous_
-  state and is discarded, because the draft is a deep copy. Under `'structural-sharing'` the
-  draft may still share that reference, so the write happens to survive. Always mutate the
-  entity passed to your handler rather than one fetched through the api.
+  state. Whether the write also survives depends on whether that entity has been copied yet, under
+  either strategy. Always mutate the entity passed to your handler rather than one fetched through
+  the api.
 
 An unsupported strategy throws a `TypeError` at store creation:
 
 ```javascript
 createStore({ types, entities, updateStrategy: "immutable" })
-// TypeError: Unsupported update strategy: immutable. Expected one of: structural-sharing, full-clone.
+// TypeError: Unsupported update strategy: immutable. Expected one of: structural-sharing, copy-on-dispatch.
 ```
 
 #### Auto-Create Entities
@@ -1325,6 +1449,7 @@ Each handler receives three arguments:
 - **`patch` / `replace`** - change a thing that is already standing, the first touching only
   what it names and the second installing all of it
 - **`update`** - the frame tick, disabled while the world is paused
+- **`stateChange`** - broadcast by `fsm()` when an entity moves, with `{ entityId, from, to }`
 
 #### Pausing the world
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "11.2.0",
+  "version": "12.0.0",
   "description": "A state manager for real-time, collaborative apps, inspired by game development patterns and compatible with Redux.",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -40,9 +40,29 @@
       "types": "./types/migration/rtk.d.ts",
       "import": "./src/migration/rtk.js"
     },
+    "./async": {
+      "types": "./types/behaviors/async.d.ts",
+      "import": "./src/behaviors/async.js"
+    },
+    "./optimistic": {
+      "types": "./types/behaviors/optimistic.d.ts",
+      "import": "./src/behaviors/optimistic.js"
+    },
+    "./fsm": {
+      "types": "./types/behaviors/state-machine/fsm.d.ts",
+      "import": "./src/behaviors/state-machine/fsm.js"
+    },
+    "./scenes": {
+      "types": "./types/behaviors/state-machine/scenes.d.ts",
+      "import": "./src/behaviors/state-machine/scenes.js"
+    },
+    "./*.js": {
+      "types": "./types/*.d.ts",
+      "import": "./src/*.js"
+    },
     "./*": {
       "types": "./types/*.d.ts",
-      "import": "./src/*"
+      "import": "./src/*.js"
     }
   },
   "files": [
@@ -55,11 +75,11 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@inglorious/utils": "5.0.0",
+    "@inglorious/utils": "5.1.0",
     "mutative": "^1.3.0"
   },
   "peerDependencies": {
-    "@inglorious/utils": "5.0.0"
+    "@inglorious/utils": "5.1.0"
   },
   "devDependencies": {
     "@inglorious/eslint-config": "1.1.4",

package/src/{async.js → behaviors/async.js}

@@ -5,7 +5,7 @@
  * success, error, and finally. The lifecycle events are automatically scoped based
  * on the provided options.
  *
- * @template {import('./store').BaseEntity} TEntity - The entity type
+ * @template {import('../store').BaseEntity} TEntity - The entity type
  * @template TPayload - The payload type passed to the operation
  * @template TResult - The result type returned by the async operation
  *
@@ -13,19 +13,19 @@
  *   Generated handlers will be named: `type`, `typeStart`, `typeRun`, `typeSuccess`, `typeError`, `typeFinally`
  *
  * @param {Object} handlers - The handler functions for each lifecycle stage.
- * @param {(entity: TEntity, payload: TPayload, api: import('./store').Api) => void} [handlers.start]
+ * @param {(entity: TEntity, payload: TPayload, api: import('../store').Api) => void} [handlers.start]
  *   Called synchronously before the async operation starts.
  *   Use for setting loading states. Receives: (entity, payload, api)
- * @param {(payload: TPayload, api: import('./store').Api) => Promise<TResult> | TResult} handlers.run
+ * @param {(payload: TPayload, api: import('../store').Api) => Promise<TResult> | TResult} handlers.run
  *   The async operation to perform. Must return a Promise or value.
  *   **Note:** Receives (payload, api) - NOT entity. Entity state should be modified in other handlers.
- * @param {(entity: TEntity, result: TResult, api: import('./store').Api) => void} [handlers.success]
+ * @param {(entity: TEntity, result: TResult, api: import('../store').Api) => void} [handlers.success]
  *   Called when the operation succeeds.
  *   Receives: (entity, result, api) where result is the resolved value from run()
- * @param {(entity: TEntity, error: any, api: import('./store').Api) => void} [handlers.error]
+ * @param {(entity: TEntity, error: any, api: import('../store').Api) => void} [handlers.error]
  *   Called when the operation fails.
  *   Receives: (entity, error, api) where error is the caught exception
- * @param {(entity: TEntity, api: import('./store').Api) => void} [handlers.finally]
+ * @param {(entity: TEntity, api: import('../store').Api) => void} [handlers.finally]
  *   Called after the operation completes (success or failure).
  *   Use for cleanup, resetting loading states. Receives: (entity, api)
  *

package/src/{optimistic.js → behaviors/optimistic.js}

@@ -8,13 +8,13 @@ const START = 0
  * Pass either a static shallow patch object or a factory that returns one.
  * The wrapper applies the patch during `Start` and rolls it back during `Error`.
  *
- * @template {import('./store').BaseEntity} TEntity
+ * @template {import('../store').BaseEntity} TEntity
  * @template TPayload
  * @template TResult
  * @template {string} TType
  *
  * @param {import('./async').AsyncEvents<TType, TEntity, TPayload, TResult>} behavior
- * @param {Record<string, any> | ((entity: TEntity, payload: TPayload, api: import('./store').Api) => Record<string, any> | null | undefined)} optimistic
+ * @param {Record<string, any> | ((entity: TEntity, payload: TPayload, api: import('../store').Api) => Record<string, any> | null | undefined)} optimistic
  *   Shallow patch applied optimistically on start, or a factory that returns it.
  *
  * @returns {import('./async').AsyncEvents<TType, TEntity, TPayload, TResult>}

package/src/behaviors/state-machine/fsm.js

@@ -0,0 +1,55 @@
+const DEFAULT_STATE = "default"
+
+export function fsm(states) {
+  const uniqueEventNames = [
+    ...new Set(Object.values(states).flatMap(Object.keys)),
+  ]
+
+  return (type) => {
+    return {
+      create(entity, payload, api) {
+        type.create?.(entity, payload, api)
+
+        entity.state ??= DEFAULT_STATE
+      },
+
+      ...uniqueEventNames.reduce(
+        (acc, eventName) => ({
+          ...acc,
+
+          [eventName](entity, event, api) {
+            const from = entity.state
+
+            // A state answers for itself, and what it has to say replaces what the type
+            // would have said. The type-stage handler is the default -- the thing every
+            // state would otherwise do -- and a state takes it over by naming the same
+            // event, which is how a state can take the way out for itself rather than
+            // being quit by, without whatever answers by default having to know that
+            // state exists.
+            const handler = states[entity.state]?.[eventName] ?? type[eventName]
+
+            handler?.(entity, event, api)
+
+            announce(entity, from, api)
+          },
+        }),
+        {},
+      ),
+    }
+  }
+}
+
+/**
+ * A machine announces where it has landed, but only when it has actually moved: a
+ * handler that reads the state without changing it should not wake anything up.
+ *
+ * The announcement is broadcast and carries the id, rather than being addressed to
+ * this entity, because what wants to hear it is usually something else.
+ */
+function announce(entity, from, api) {
+  const to = entity.state
+
+  if (to === from) return
+
+  api.notify("stateChange", { entityId: entity.id, from, to })
+}

package/src/behaviors/state-machine/scenes.js

@@ -0,0 +1,89 @@
+import { isDeepEqual } from "@inglorious/utils/object.js"
+
+/**
+ * Puts an entity up, and takes down whatever the state before it had up.
+ *
+ * A state machine says when it moves; this says what each state is made of, and is
+ * usually the pair to `fsm`. Together they cover the ordinary case of a game that is a
+ * few screens and a world that survives the move between them -- a menu has nothing on it
+ * that the play has, and two states of the same play have all of it in common.
+ *
+ * Only the difference between two states is touched. Anything they have in common is
+ * left standing as it is, which is what carries whatever the two share from one into the
+ * next without rebuilding it, and so without losing whatever the world has already done
+ * to it.
+ *
+ * A thing that stands on both sides but is not configured the same way is patched rather
+ * than rebuilt, so one state may take over part of it -- a keyboard whose keys mean
+ * something else there -- without the rest of it being torn up to make room.
+ *
+ * @example
+ * ```js
+ * import { fsm } from "@inglorious/store/fsm"
+ * import { scenes } from "@inglorious/store/scenes"
+ *
+ * const SCENES = {
+ *   title: () => [createTitleEntity(), createMenuEntity()],
+ *   play: () => [createPaddleEntity(), createBallEntity()],
+ * }
+ *
+ * const types = {
+ *   Game: [scenes(SCENES), fsm({ title: { start(e) { e.state = "play" } } })],
+ * }
+ *
+ * const entities = { game: { type: "Game", state: "title" } }
+ * ```
+ *
+ * @param {object} scenesByState - What stands in each state, given the state and the
+ *   entity asking. Returns the entity configurations to have standing.
+ * @returns {object} The behaviour.
+ */
+export function scenes(scenesByState) {
+  function build(entity, state, api) {
+    const leaving = entity.scene ?? []
+    const arriving = scenesByState[state]?.(entity) ?? []
+
+    const leavingIds = leaving.map(({ id }) => id)
+    const arrivingIds = arriving.map(({ id }) => id)
+
+    for (const { id } of leaving) {
+      if (arrivingIds.includes(id)) continue
+
+      api.notify("remove", id)
+    }
+
+    for (const added of arriving) {
+      if (!leavingIds.includes(added.id)) {
+        api.notify("add", added)
+
+        continue
+      }
+
+      // The same thing stands on both sides of the move, so it is neither added nor
+      // removed -- but it may be wanted to be a different thing now, and then only what
+      // has actually changed is merged over it. That is what leaves a shared thing where
+      // the world had put it when the next state says nothing different about it.
+      const previous = leaving.find(({ id }) => id === added.id)
+
+      if (!isDeepEqual(previous, added)) {
+        api.notify("patch", added)
+      }
+    }
+
+    entity.scene = arriving
+  }
+
+  return {
+    create(entity, payload, api) {
+      build(entity, entity.state, api)
+    },
+
+    // The announcement is broadcast and carries the id, so that anything else listening
+    // for it can tell which machine moved. This one is only interested in its own.
+    stateChange(entity, { entityId, to }, api) {
+      if (entityId !== entity.id) return
+
+      build(entity, to, api)
+    },
+  }
+}

package/src/client/multiplayer-middleware.js

@@ -2,18 +2,6 @@ import { deserialize, extend, serialize } from "@inglorious/utils/object.js"
 
 const DEFAULT_RECONNECTION_DELAY = 1000
 
-/**
- * Where the server is, when the caller has not said.
- *
- * Read when it is asked for rather than when this module is imported, so that importing it
- * does not require a browser -- which is what lets the store be imported anywhere.
- *
- * @returns {string} The server's WebSocket URL.
- */
-function defaultServerUrl() {
-  return `ws://${window.location.hostname}:3000`
-}
-
 /**
  * Creates and returns the multiplayer middleware.
  * @returns {Function} The middleware function.
@@ -102,3 +90,15 @@ export function multiplayerMiddleware(config = {}) {
     }
   }
 }
+
+/**
+ * Where the server is, when the caller has not said.
+ *
+ * Read when it is asked for rather than when this module is imported, so that importing it
+ * does not require a browser -- which is what lets the store be imported anywhere.
+ *
+ * @returns {string} The server's WebSocket URL.
+ */
+function defaultServerUrl() {
+  return `ws://${window.location.hostname}:3000`
+}

package/src/migration/rtk.js

@@ -7,7 +7,7 @@
 
 import { extend } from "@inglorious/utils/object.js"
 
-import { handleAsync } from "../async"
+import { handleAsync } from "../behaviors/async.js"
 
 const SEP_LENGTH = 50
 const INDENT_SPACES = 2

package/src/store.js

@@ -1,3 +1,4 @@
+import { clone } from "@inglorious/utils/data-structures/object.js"
 import { toCamelCase } from "@inglorious/utils/data-structures/string.js"
 import { create } from "mutative"
 
@@ -10,10 +11,10 @@ import { augmentType, augmentTypes } from "./types.js"
 /** Copies only the entities that change, using a draft proxy. */
 const STRUCTURAL_SHARING = "structural-sharing"
 
-/** Deep-clones the whole state and applies events to the copy, without a proxy. */
-const FULL_CLONE = "full-clone"
+/** Deep-copies each entity as it is handed out, and applies events to the copy, without a proxy. */
+const COPY_ON_DISPATCH = "copy-on-dispatch"
 
-const UPDATE_STRATEGIES = [STRUCTURAL_SHARING, FULL_CLONE]
+const UPDATE_STRATEGIES = [STRUCTURAL_SHARING, COPY_ON_DISPATCH]
 
 /**
  * Creates a store to manage state and events.
@@ -25,10 +26,10 @@ const UPDATE_STRATEGIES = [STRUCTURAL_SHARING, FULL_CLONE]
  *   that actually changed are copied. Unchanged entities keep their previous reference, which
  *   makes change detection cheap for consumers that rely on reference equality. This is the
  *   right choice for UI stores, where a small number of entities change at a time.
- * - `"full-clone"` - Deep-clones the whole state with `structuredClone` and applies events directly
- *   to the copy, without a proxy. The cost is proportional to the total state size on every
- *   update, but there is no per-entity proxy overhead, so it scales better when thousands of
- *   entities change every frame, as in a game simulation.
+ * - `"copy-on-dispatch"` - Deep-copies each entity the first time it is handed to a handler or read by
+ *   a system, and applies events directly to the copy, without a proxy. Entities nothing touches
+ *   are not copied, and there is no per-entity proxy overhead, so it scales better when
+ *   thousands of entities change every frame, as in a game simulation.
  *
  * Under both strategies the current state is kept intact while the queued events are applied to a
  * separate draft, and the two are swapped only once every event has been processed. Handlers and
@@ -132,14 +133,14 @@ export function createStore({
     let nextState
 
     if (updateStrategy === STRUCTURAL_SHARING) {
-      nextState = create(state, patch, {
+      nextState = create(state, (draft) => patch(writeThrough(draft)), {
         enableAutoFreeze: state.game?.devMode,
       })
     } else {
-      const draft = structuredClone(state)
+      const draft = copyOnDispatch(state)
 
       patch(draft)
-      nextState = draft
+      nextState = draft.entities
     }
 
     state = nextState
@@ -152,9 +153,10 @@ export function createStore({
     /**
      * Applies every queued event to the given draft.
      *
-     * The draft is either the proxy returned by `create` (structural sharing) or the
-     * deep copy produced by `structuredClone` (full clone). The current state is not
-     * modified, and only becomes the new state once this function returns.
+     * The draft wraps either the proxy returned by `create` (structural sharing) or a
+     * copy of the entity map whose entities are copied as they are handed out (copy on
+     * dispatch). The current state is not modified, and only becomes the new state once
+     * this function returns.
      *
      * A change made by a handler is not visible to the next handler in the same pass:
      * `getState` still returns the state as it was before the pass began. This is on
@@ -163,7 +165,7 @@ export function createStore({
      * left is asking about the past. Anything reacting to a change should be told the
      * change rather than go looking for it.
      *
-     * @param {Entities} draft - The draft to apply the queued events to.
+     * @param {Draft} draft - The draft to apply the queued events to.
      * @returns {void}
      */
     function patch(draft) {
@@ -247,24 +249,26 @@ export function createStore({
         const halted = isHalted && handlerName === "update"
 
         for (const id of entityIds) {
-          const entity = draft[id]
+          // Looked at before it is taken, because an entity the pause holds back is
+          // not going to be written to, and taking it would copy it for nothing.
+          const entity = draft.entities[id]
           const type = types[entity.type]
 
           if (halted && !entity.updatesWhilePaused) continue
 
           const handle = type[handlerName]
 
-          handle?.(entity, event.payload, api)
+          handle?.(draft.take(id), event.payload, api)
         }
 
         if (event.type.endsWith(":destroy")) {
           const [target] = event.type.split(":")
           const [, id] = target.split("#")
-          const entity = draft[id]
+          const entity = draft.entities[id]
           if (entity) {
             const type = types[entity.type]
             const typeName = entity.type
-            delete draft[id]
+            delete draft.entities[id]
 
             eventMap.removeEntity(id, type, typeName)
           }
@@ -273,7 +277,7 @@ export function createStore({
         // Systems process events by handler name (not scoped)
         systems.forEach((system) => {
           const handle = system[handlerName]
-          handle?.(draft, event.payload, api)
+          handle?.(draft.forSystems, event.payload, api)
         })
       }
     }
@@ -423,7 +427,7 @@ export function createStore({
 
     entitiesToCreate.forEach((id) => {
       const entity = newEntities[id]
-      addEntity(state, { id, ...entity })
+      addEntity(writeThrough(state), { id, ...entity })
     })
 
     entitiesToUpdate.forEach((id) => {
@@ -445,7 +449,7 @@ export function createStore({
         )
 
         if (!hasEntity) {
-          addEntity(state, { id: entityId, type: typeName })
+          addEntity(writeThrough(state), { id: entityId, type: typeName })
         }
       }
     }
@@ -462,13 +466,13 @@ export function createStore({
 
   /**
    * Adds an entity to the state and registers its event handlers.
-   * @param {Entities} draft - The draft (structural sharing) or the copy (full clone) to mutate.
+   * @param {Draft} draft - The draft to put it in.
    * @param {Entity} payload - The entity to add, including its id.
    * @returns {void}
    */
   function addEntity(draft, payload) {
     const { id, ...entity } = payload
-    draft[id] = augmentEntity(id, entity)
+    draft.put(id, augmentEntity(id, entity))
     const type = types[entity.type]
 
     eventMap.addEntity(id, type, entity.type)
@@ -482,7 +486,7 @@ export function createStore({
    * as being half a sort, so naming a different one means taking the thing out of the old
    * one's list of entities before putting it in the new one.
    *
-   * @param {Entities} draft - The draft (structural sharing) or the copy (full clone) to mutate.
+   * @param {Draft} draft - The draft it stands in.
    * @param {string} id - The thing being moved.
    * @param {string} previousType - The type it was under.
    * @param {string|undefined} type - The type it is under now, if it has named one.
@@ -503,20 +507,22 @@ export function createStore({
    * new configuration says otherwise. A field named as `undefined` is set to nothing,
    * which is what taking a key off a mapping means.
    *
-   * @param {Entities} draft - The draft (structural sharing) or the copy (full clone) to mutate.
+   * @param {Draft} draft - The draft to change it in.
    * @param {Entity} payload - The thing and the fields to merge into it.
    * @returns {void}
    */
   function patchEntity(draft, payload) {
     const { id, ...config } = payload
-    const existing = draft[id]
+    // Taken rather than looked at, because the merge keeps whatever the configuration
+    // does not mention, and what it keeps must not be shared with the previous state.
+    const existing = draft.take(id)
 
     // Configuring something that is not there is not a thing that can be done. The world
     // is built in one pass, so a scene naming a thing another scene is yet to put up is
     // ordinary rather than a mistake, and is not worth failing over.
     if (!existing) return
 
-    draft[id] = augmentEntity(id, { ...existing, ...config })
+    draft.put(id, augmentEntity(id, { ...existing, ...config }))
 
     moveToType(draft, id, existing.type, config.type)
   }
@@ -529,24 +535,25 @@ export function createStore({
    * nothing here as much as it is in a patch -- the difference between the two is what
    * happens to the fields neither mentions.
    *
-   * @param {Entities} draft - The draft (structural sharing) or the copy (full clone) to mutate.
+   * @param {Draft} draft - The draft to change it in.
    * @param {Entity} payload - The thing and the fields it is to be.
    * @returns {void}
    */
   function replaceEntity(draft, payload) {
     const { id, ...config } = payload
-    const existing = draft[id]
+    const existing = draft.entities[id]
 
     if (!existing) return
 
-    draft[id] = augmentEntity(id, config)
+    draft.put(id, augmentEntity(id, config))
 
     moveToType(draft, id, existing.type, config.type)
   }
 
   /**
    * Queues the destruction of an entity. The entity is removed by the `#id:destroy` event.
-   * @param {Entities} draft - The draft (structural sharing) or the copy (full clone) to mutate.
+   * @param {Draft|Entities} draft - Where it stands. The removal itself is queued, so
+   *   nothing is written to it here.
    * @param {string} id - The id of the entity to remove.
    * @returns {void}
    */
@@ -555,6 +562,83 @@ export function createStore({
   }
 }
 
+/**
+ * A draft that writes straight into the entities it is given.
+ *
+ * This is the whole of structural sharing's draft, because Mutative's proxy already copies
+ * an entity the moment it is written to, and of the state being built by `setState`,
+ * which has no previous state to protect.
+ *
+ * @param {Entities} entities - The entities to write into.
+ * @returns {Draft} The draft.
+ */
+function writeThrough(entities) {
+  return {
+    entities,
+    forSystems: entities,
+    take: (id) => entities[id],
+    put(id, entity) {
+      entities[id] = entity
+    },
+  }
+}
+
+/**
+ * A draft that copies an entity the first time it is handed to anything that could
+ * write to it.
+ *
+ * This is what `copy-on-dispatch` is named after: an entity is copied when an event is
+ * dispatched to it, and the entities that nothing touches are never paid for. The map is
+ * copied straight away, which is cheap -- a reference for every entity -- and an entity
+ * is deep-copied only when it is taken: handed to one of its handlers, merged by a
+ * `patch`, or read by a system. A frame on which only the pointer moves copies the
+ * pointer, and a frame on which nothing at all happens copies nothing but the map.
+ *
+ * There is no proxy on the entities themselves, which is what still sets this apart
+ * from structural sharing: a handler is given a plain object, and pays nothing for
+ * writing to it however many times it does. The one proxy is over the map handed to
+ * systems, which have no single entity to be given and so have to be given all of them.
+ * Each entity a system reads through it is taken, which means a system that walks every
+ * entity copies every entity: one that only needs to know how things stood can ask
+ * `api.getEntities()` instead, and take only what it writes to.
+ *
+ * @param {Entities} state - The state to leave as it is.
+ * @returns {Draft} The draft.
+ */
+function copyOnDispatch(state) {
+  const entities = { ...state }
+  const taken = new Set()
+
+  function take(id) {
+    if (!taken.has(id) && Object.hasOwn(entities, id)) {
+      entities[id] = clone(entities[id])
+      taken.add(id)
+    }
+
+    return entities[id]
+  }
+
+  function put(id, entity) {
+    entities[id] = entity
+    taken.add(id)
+  }
+
+  const forSystems = new Proxy(entities, {
+    get(target, key, receiver) {
+      return typeof key === "string" && Object.hasOwn(target, key)
+        ? take(key)
+        : Reflect.get(target, key, receiver)
+    },
+
+    set(target, key, value) {
+      put(key, value)
+      return true
+    },
+  })
+
+  return { entities, forSystems, take, put }
+}
+
 /**
  * Validates the given update strategy.
  * @param {UpdateStrategy} updateStrategy - The update strategy to validate.
@@ -572,12 +656,17 @@ function assertUpdateStrategy(updateStrategy) {
 }
 
 /**
- * @typedef {"structural-sharing" | "full-clone"} UpdateStrategy - How the state is copied before events are applied.
+ * @typedef {"structural-sharing" | "copy-on-dispatch"} UpdateStrategy - How the state is copied before events are applied.
  * @typedef {Object} StoreConfig - Configuration options accepted by {@link createStore}.
  * @typedef {Object.<string, any>} Type - An augmented entity type.
  * @typedef {Object.<string, Type>} Types - A collection of augmented types.
  * @typedef {Object.<string, any>} Entity - An object representing an entity.
  * @typedef {Object.<string, Entity>} Entities - A collection of entities indexed by id.
+ * @typedef {Object} Draft - The entities an update writes to, and how it gets at them.
+ * @property {Entities} Draft.entities - The entities being built, read without copying.
+ * @property {Entities} Draft.forSystems - The entities as handed to systems.
+ * @property {(id: string) => Entity|undefined} Draft.take - The entity to write to.
+ * @property {(id: string, entity: Entity) => void} Draft.put - Sets an entity outright.
  * @typedef {(listener: () => void) => () => void} Listener - Subscribes to state updates and returns an unsubscribe function.
  * @typedef {Object} Store - The store returned by {@link createStore}.
  */

package/types/{async.d.ts → behaviors/async.d.ts}

@@ -1,5 +1,5 @@
-import { Api } from "./api"
-import { BaseEntity } from "./store"
+import { Api } from "../api"
+import { BaseEntity } from "../store"
 
 /**
  * Scope option for async handler events

package/types/{optimistic.d.ts → behaviors/optimistic.d.ts}

@@ -1,6 +1,6 @@
-import { Api } from "./api"
+import { Api } from "../api"
 import { AsyncEvents } from "./async"
-import { BaseEntity } from "./store"
+import { BaseEntity } from "../store"
 
 /**
  * Decorates an async behavior with optimistic update boilerplate.

package/types/behaviors/state-machine/fsm.d.ts

@@ -0,0 +1,109 @@
+import type { Api } from "../../api"
+import type { BaseEntity, EntityType, EventHandler } from "../../store"
+
+/** The state an entity is in until a handler moves it. */
+export type DefaultState = "default"
+
+/**
+ * The states an entity can be in: the values of its `state` field, as declared
+ * on its interface. An entity that declares no `state` can be in any.
+ */
+export type StateOf<TEntity extends BaseEntity> = TEntity extends {
+  state?: infer TState extends string
+}
+  ? TState
+  : string
+
+/**
+ * What one state answers to: its handlers, by event name. A handler moves the
+ * entity by assigning `entity.state`.
+ */
+export type FsmState<
+  TEntity extends BaseEntity = BaseEntity,
+  TApi extends Api = Api,
+> = {
+  [eventName: string]: EventHandler<TEntity, TApi> | undefined
+}
+
+/**
+ * Each state's handlers, by state name. A state that answers nothing of its
+ * own can be left out, and then it answers what the type does.
+ */
+export type FsmStates<
+  TEntity extends BaseEntity = BaseEntity,
+  TApi extends Api = Api,
+> = {
+  [TState in StateOf<TEntity> | DefaultState]?: FsmState<TEntity, TApi>
+}
+
+/**
+ * The payload of `stateChange`, which `fsm` broadcasts whenever a handler has
+ * moved the entity: the entity's id, the state it left and the one it is in.
+ */
+export interface StateChangePayload<TState extends string = string> {
+  entityId: string
+  from: TState
+  to: TState
+}
+
+/**
+ * Makes a type a finite state machine, in the manner of the OOP State pattern:
+ * what the entity does on an event depends on the state it is in.
+ *
+ * Each state names the events it answers. A state's handler replaces the
+ * type's handler for the same event, so the type's handler is what every state
+ * does by default and a state takes it over by naming the event. A handler
+ * moves the entity by assigning `entity.state`; the entity starts in its own
+ * `state`, or in `"default"` when it has none.
+ *
+ * After a handler has moved the entity, the machine broadcasts `stateChange`
+ * with a `StateChangePayload`. A handler that leaves the state as it was
+ * announces nothing.
+ *
+ * The entity and the api are inferred from where the behavior is used, such as
+ * `types: { Door: [Door, fsm({ ... })] }` in a typed store. Declaring `state`
+ * on the entity's interface checks the state names as well.
+ *
+ * @example
+ * ```typescript
+ * interface DoorEntity extends BaseEntity {
+ *   type: "Door"
+ *   state: "closed" | "open" | "locked"
+ * }
+ *
+ * const types = {
+ *   Door: [
+ *     { knock: (entity) => console.log("Nobody's home") },
+ *     fsm({
+ *       closed: {
+ *         open(entity) {
+ *           entity.state = "open"
+ *         },
+ *         lock(entity) {
+ *           entity.state = "locked"
+ *         },
+ *       },
+ *       open: {
+ *         close(entity) {
+ *           entity.state = "closed"
+ *         },
+ *       },
+ *       locked: {
+ *         unlock(entity) {
+ *           entity.state = "closed"
+ *         },
+ *       },
+ *     }),
+ *   ],
+ * }
+ * ```
+ *
+ * @param states - Each state's handlers, by state name
+ * @returns A behavior that wraps the type it is applied to
+ */
+export function fsm<
+  TEntity extends BaseEntity = BaseEntity,
+  TApi extends Api = Api,
+>(
+  states: FsmStates<TEntity, TApi>,
+): (type: EntityType<TEntity, TApi>) => EntityType<TEntity, TApi>

package/types/behaviors/state-machine/scenes.d.ts

@@ -0,0 +1,53 @@
+import type { Api } from "../../api"
+import type { StateOf } from "./fsm"
+import type { BaseEntity, EntityType, Stored } from "../../store"
+
+/**
+ * An entity a scene puts up. It needs its `id`, which is how two scenes tell
+ * what they have in common.
+ */
+export type SceneEntity = BaseEntity & {
+  id: string
+  [field: string]: unknown
+}
+
+/**
+ * What stands in each state, by state name: a function of the entity running
+ * the machine that returns the entities to have standing. A state left out has
+ * nothing standing.
+ */
+export type ScenesByState<TEntity extends BaseEntity = BaseEntity> = {
+  [TState in StateOf<TEntity>]?: (entity: Stored<TEntity>) => SceneEntity[]
+}
+
+/**
+ * Puts a state's entities up and takes down whatever the state before it had
+ * up. It is usually paired with `fsm`, which says when the state moves: on
+ * `create` it builds the entity's current state, and on its own `stateChange`
+ * it builds the state it moved to.
+ *
+ * Only the difference between two states is touched: an entity that is in
+ * both is left standing, and is patched rather than rebuilt when the next
+ * state configures it differently. Entities are compared by `id`, and the
+ * entity running the machine keeps what it has up in `scene`.
+ *
+ * @example
+ * ```typescript
+ * const types = {
+ *   Game: [
+ *     scenes({
+ *       title: () => [{ id: "menu", type: "Menu" }],
+ *       play: () => [{ id: "board", type: "Board" }],
+ *     }),
+ *     fsm({ title: { start(entity) { entity.state = "play" } } }),
+ *   ],
+ * }
+ * ```
+ *
+ * @param scenesByState - What stands in each state
+ * @returns A behavior handling `create` and `stateChange`
+ */
+export function scenes<
+  TEntity extends BaseEntity = BaseEntity,
+  TApi extends Api = Api,
+>(scenesByState: ScenesByState<TEntity>): EntityType<TEntity, TApi>

package/types/index.d.ts

@@ -1,5 +1,5 @@
 export * from "./api"
-export * from "./async"
+export * from "./behaviors/async"
 export * from "./select"
 export * from "./store"
 export * from "./test"

package/types/store.d.ts

@@ -154,17 +154,17 @@ export type UpdateMode = "auto" | "manual"
  * - `"structural-sharing"` (default) applies events to a draft proxy, so only the entities that
  *   actually changed are copied. Unchanged entities keep their previous reference, which keeps
  *   reference-equality change detection cheap. Best for UI stores.
- * - `"full-clone"` deep-clones the whole state with `structuredClone` and applies events to the
- *   copy without a proxy. Cost is proportional to the total state size per update, but there is
- *   no per-entity proxy overhead, so it scales better when thousands of entities change every
- *   frame, as in a game simulation.
+ * - `"copy-on-dispatch"` deep-copies each entity the first time it is handed to a handler or read by a
+ *   system, and applies events to the copy without a proxy. Entities nothing touches are not
+ *   copied, and there is no per-entity proxy overhead, so it scales better when thousands of
+ *   entities change every frame, as in a game simulation.
  *
  * Under both strategies the current state is left intact while the queued events are applied to
  * a separate draft, and the two are swapped only once every event has been processed. This means
  * that during an update `api.getEntity()` and `api.getEntities()` read the previous state rather
  * than the in-flight changes.
  */
-export type UpdateStrategy = "structural-sharing" | "full-clone"
+export type UpdateStrategy = "structural-sharing" | "copy-on-dispatch"
 
 /**
  * Store configuration