@typeonce/ritmo 0.7.0 → 0.9.0

package/dist/FixedLoop.js

@@ -0,0 +1,97 @@
+import * as Result from "./Result.js";
+/** Wraps a host-specific subscription function in the canonical source type. */
+export const source = (subscribe) => ({ subscribe });
+const validate = (options) => {
+    for (const field of ["maxFrameSeconds"]) {
+        const value = options[field];
+        if (!Number.isFinite(value) || value <= 0) {
+            return Result.failure({
+                kind: "InvalidFixedLoopOptions",
+                field,
+                reason: "mustBeFiniteAndPositive",
+                value
+            });
+        }
+    }
+    if (!Number.isInteger(options.maxStepsPerFrame) || options.maxStepsPerFrame <= 0) {
+        return Result.failure({
+            kind: "InvalidFixedLoopOptions",
+            field: "maxStepsPerFrame",
+            reason: "mustBePositiveInteger",
+            value: options.maxStepsPerFrame
+        });
+    }
+    return Result.success(undefined);
+};
+/**
+ * Starts a fixed-step loop after validating its timing policy.
+ *
+ * Update failures and malformed host ticks are delivered to `onFailure`, then
+ * the driver stops. Render defects are deliberately not caught: they are
+ * programmer defects, not expected game outcomes.
+ */
+export const start = (options) => {
+    const validity = validate(options);
+    if (!validity.ok) {
+        return validity;
+    }
+    let accumulator = 0;
+    let stopped = false;
+    let hostSubscription;
+    const stop = () => {
+        if (stopped) {
+            return;
+        }
+        stopped = true;
+        hostSubscription?.stop();
+    };
+    const fail = (failure) => {
+        stop();
+        options.onFailure(failure);
+    };
+    const onTick = (tick) => {
+        if (stopped) {
+            return;
+        }
+        if (!Number.isFinite(tick.deltaMS) || tick.deltaMS < 0) {
+            fail({ kind: "InvalidTickDelta", deltaMS: tick.deltaMS });
+            return;
+        }
+        const rawSeconds = tick.deltaMS / 1000;
+        const elapsedSeconds = Math.min(rawSeconds, options.maxFrameSeconds);
+        let droppedSeconds = rawSeconds - elapsedSeconds;
+        accumulator += elapsedSeconds;
+        let fixedSteps = 0;
+        while (accumulator >= options.step.dt && fixedSteps < options.maxStepsPerFrame) {
+            const update = options.update(options.step.dt);
+            if (!update.ok) {
+                fail({ kind: "UpdateFailure", error: update.error });
+                return;
+            }
+            accumulator -= options.step.dt;
+            fixedSteps += 1;
+        }
+        if (accumulator >= options.step.dt) {
+            const droppedWholeSteps = Math.floor(accumulator / options.step.dt) * options.step.dt;
+            accumulator -= droppedWholeSteps;
+            droppedSeconds += droppedWholeSteps;
+        }
+        options.render({
+            elapsedSeconds,
+            fixedSteps,
+            alpha: accumulator / options.step.dt,
+            droppedSeconds
+        });
+    };
+    hostSubscription = options.source.subscribe(onTick);
+    if (stopped) {
+        hostSubscription.stop();
+    }
+    return Result.success({
+        stop,
+        reset() {
+            accumulator = 0;
+        }
+    });
+};
+//# sourceMappingURL=FixedLoop.js.map

package/dist/FixedLoop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FixedLoop.js","sourceRoot":"","sources":["../src/FixedLoop.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AA+ErC,gFAAgF;AAChF,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,SAAyC,EACtB,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAA;AAEvC,MAAM,QAAQ,GAAG,CAAC,OAAgB,EAAuC,EAAE;IACzE,KAAK,MAAM,KAAK,IAAI,CAAC,iBAAiB,CAAU,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;QAC5B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;YAC1C,OAAO,MAAM,CAAC,OAAO,CAAC;gBACpB,IAAI,EAAE,yBAAyB;gBAC/B,KAAK;gBACL,MAAM,EAAE,yBAAyB;gBACjC,KAAK;aACN,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,gBAAgB,CAAC,IAAI,OAAO,CAAC,gBAAgB,IAAI,CAAC,EAAE,CAAC;QACjF,OAAO,MAAM,CAAC,OAAO,CAAC;YACpB,IAAI,EAAE,yBAAyB;YAC/B,KAAK,EAAE,kBAAkB;YACzB,MAAM,EAAE,uBAAuB;YAC/B,KAAK,EAAE,OAAO,CAAC,gBAAgB;SAChC,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;AAClC,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,OAAyC,EACF,EAAE;IACzC,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAA;IAClC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED,IAAI,WAAW,GAAG,CAAC,CAAA;IACnB,IAAI,OAAO,GAAG,KAAK,CAAA;IACnB,IAAI,gBAA0C,CAAA;IAE9C,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,IAAI,OAAO,EAAE,CAAC;YACZ,OAAM;QACR,CAAC;QACD,OAAO,GAAG,IAAI,CAAA;QACd,gBAAgB,EAAE,IAAI,EAAE,CAAA;IAC1B,CAAC,CAAA;IAED,MAAM,IAAI,GAAG,CAAC,OAA6B,EAAQ,EAAE;QACnD,IAAI,EAAE,CAAA;QACN,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;IAC5B,CAAC,CAAA;IAED,MAAM,MAAM,GAAG,CAAC,IAAW,EAAQ,EAAE;QACnC,IAAI,OAAO,EAAE,CAAC;YACZ,OAAM;QACR,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;YACvD,IAAI,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;YACzD,OAAM;QACR,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;QACtC,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,eAAe,CAAC,CAAA;QACpE,IAAI,cAAc,GAAG,UAAU,GAAG,cAAc,CAAA;QAChD,WAAW,IAAI,cAAc,CAAA;QAE7B,IAAI,UAAU,GAAG,CAAC,CAAA;QAClB,OAAO,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,UAAU,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAC/E,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;YAC9C,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;gBACf,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAA;gBACpD,OAAM;YACR,CAAC;YACD,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAA;YAC9B,UAAU,IAAI,CAAC,CAAA;QACjB,CAAC;QAED,IAAI,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACnC,MAAM,iBAAiB,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,CAAA;YACrF,WAAW,IAAI,iBAAiB,CAAA;YAChC,cAAc,IAAI,iBAAiB,CAAA;QACrC,CAAC;QAED,OAAO,CAAC,MAAM,CAAC;YACb,cAAc;YACd,UAAU;YACV,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE;YACpC,cAAc;SACf,CAAC,CAAA;IACJ,CAAC,CAAA;IAED,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;IACnD,IAAI,OAAO,EAAE,CAAC;QACZ,gBAAgB,CAAC,IAAI,EAAE,CAAA;IACzB,CAAC;IAED,OAAO,MAAM,CAAC,OAAO,CAAC;QACpB,IAAI;QACJ,KAAK;YACH,WAAW,GAAG,CAAC,CAAA;QACjB,CAAC;KACF,CAAC,CAAA;AACJ,CAAC,CAAA"}

package/dist/HostClock.d.ts

@@ -13,7 +13,7 @@
  *
  * @example
  * ```ts
- * const runtime = Game.Runtime.make({ services, debug: { hostClock: HostClock.standard } })
+ * const runtime = Game.Runtime.make({ services, debug: { hostClock: HostClock.standard } }).value
  * ```
  *
  * @module HostClock

package/dist/HostClock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HostClock.d.ts","sourceRoot":"","sources":["../src/HostClock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAA;CAC3B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAqC,CAAA;AAE5D,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CACpB;AAED,6EAA6E;AAC7E,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAA;CACxE;AAED,4EAA4E;AAC5E,eAAO,MAAM,IAAI,QAAO,aAUvB,CAAA;AAED,mFAAmF;AACnF,eAAO,MAAM,OAAO,SAAU,MAAM,MAAM,MAAM,KAAG,MAAgC,CAAA"}
+{"version":3,"file":"HostClock.d.ts","sourceRoot":"","sources":["../src/HostClock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAA;CAC3B;AAED;;;;;;GAMG;AAEH,eAAO,MAAM,QAAQ,EAAE,SAAqC,CAAA;AAE5D,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CACpB;AAED,6EAA6E;AAC7E,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAA;CACxE;AAED,4EAA4E;AAC5E,eAAO,MAAM,IAAI,QAAO,aAUvB,CAAA;AAED,mFAAmF;AACnF,eAAO,MAAM,OAAO,SAAU,MAAM,MAAM,MAAM,KAAG,MAAgC,CAAA"}

package/dist/HostClock.js

@@ -13,7 +13,7 @@
  *
  * @example
  * ```ts
- * const runtime = Game.Runtime.make({ services, debug: { hostClock: HostClock.standard } })
+ * const runtime = Game.Runtime.make({ services, debug: { hostClock: HostClock.standard } }).value
  * ```
  *
  * @module HostClock
@@ -27,6 +27,7 @@ import * as Result from "./Result.js";
  * 0. Prefer a monotonic platform clock when there is one
  * (`BrowserHostClock.make(window)`).
  */
+// oxlint-disable-next-line ritmo/use-clock-for-time -- HostClock is host time, for hosts and tools; systems read Clock.
 export const standard = { now: () => Date.now() };
 /** A test clock at 0. Every reading is the same until `adjust` moves it. */
 export const test = () => {

package/dist/HostClock.js.map

@@ -1 +1 @@
-{"version":3,"file":"HostClock.js","sourceRoot":"","sources":["../src/HostClock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAOrC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAc,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAA;AAc5D,4EAA4E;AAC5E,MAAM,CAAC,MAAM,IAAI,GAAG,GAAkB,EAAE;IACtC,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,OAAO;QACL,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO;QAClB,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE;YACb,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,GAAG,EAAE,CAAC;gBAAE,OAAO,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,EAAE,EAAE,CAAC,CAAA;YAC9H,OAAO,IAAI,EAAE,CAAA;YACb,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;QAClC,CAAC;KACF,CAAA;AACH,CAAC,CAAA;AAED,mFAAmF;AACnF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAY,EAAE,EAAU,EAAU,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,CAAA"}
+{"version":3,"file":"HostClock.js","sourceRoot":"","sources":["../src/HostClock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAOrC;;;;;;GAMG;AACH,wHAAwH;AACxH,MAAM,CAAC,MAAM,QAAQ,GAAc,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAA;AAc5D,4EAA4E;AAC5E,MAAM,CAAC,MAAM,IAAI,GAAG,GAAkB,EAAE;IACtC,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,OAAO;QACL,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO;QAClB,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE;YACb,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,GAAG,EAAE,CAAC;gBAAE,OAAO,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,EAAE,EAAE,CAAC,CAAA;YAC9H,OAAO,IAAI,EAAE,CAAA;YACb,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;QAClC,CAAC;KACF,CAAA;AACH,CAAC,CAAA;AAED,mFAAmF;AACnF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAY,EAAE,EAAU,EAAU,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,CAAA"}

package/dist/Machine.d.ts

@@ -39,6 +39,7 @@
  */
 import type { AnyScheduleOrder, Schedule } from "./Schedule.ts";
 import * as Requirement from "./Requirement.ts";
+import type * as Result from "./Result.ts";
 import type { Schema } from "./Schema.ts";
 import type { SystemFailure } from "./System.ts";
 /**
@@ -51,54 +52,62 @@ export type StateValue = string | number;
 /**
  * One schema-bound finite state machine definition.
  */
-export interface StateMachineDefinition<out Name extends string = string, out Values extends readonly [StateValue, ...StateValue[]] = readonly [StateValue, ...StateValue[]], out Root = unknown> {
+export interface StateMachineDefinition<out Name extends string = string, out Values extends readonly [StateValue, ...StateValue[]] = readonly [StateValue, ...StateValue[]], out Root = unknown, out Parent = unknown> {
     readonly kind: "stateMachine";
     readonly name: Name;
     readonly key: symbol;
     readonly values: Values;
+    /** For a sub-state: the machine and the state it exists in. */
+    readonly within?: SubStateParent | undefined;
     readonly __schemaRoot?: Root | undefined;
+    /** The machine a sub-state exists within; `unknown` for a top-level machine. */
+    readonly __parent?: (_: never) => Parent;
+}
+/** Where a sub-state exists: while `machine` is in `state`. */
+export interface SubStateParent {
+    readonly machine: StateMachine.Any;
+    readonly state: StateValue;
 }
 /**
- * The runtime-visible transition payload for one machine.
+ * Whether `M` is a sub-state (declared with `within`): it has no value while
+ * its parent machine is in another state.
  */
-export interface TransitionSnapshot<M extends StateMachineDefinition = StateMachineDefinition> {
-    readonly from: StateMachine.Value<M>;
-    readonly to: StateMachine.Value<M>;
-}
+export type IsSubState<M> = M extends {
+    readonly __parent?: (_: never) => infer Parent;
+} ? unknown extends Parent ? false : true : false;
 /**
- * A typed read-only view over the current committed state.
+ * The committed value of `M`. A sub-state has none (`undefined`) while its
+ * parent machine is not in the state it exists in; a top-level machine
+ * always has one.
  */
-export interface MachineView<M extends StateMachineDefinition = StateMachineDefinition> {
-    get(): StateMachine.Value<M>;
-    is(value: StateMachine.Value<M>): boolean;
-}
+export type CurrentValue<M extends StateMachine.Any> = IsSubState<M> extends true ? StateMachine.Value<M> | undefined : StateMachine.Value<M>;
 /**
- * A typed queued-write view over the next state.
+ * Why queuing a sub-state's next value failed: its parent machine is not in
+ * the state the sub-state exists in, so there is nothing to change.
  */
-export interface NextMachineView<M extends StateMachineDefinition = StateMachineDefinition> {
-    getPending(): StateMachine.Value<M> | undefined;
-    set(value: StateMachine.Value<M>): void;
-    setIfChanged(value: StateMachine.Value<M>): void;
-    reset(): void;
+export interface SubStateInactive {
+    readonly _tag: "SubStateInactive";
+    /** The sub-state's name. */
+    readonly machine: string;
+    /** The parent machine's name. */
+    readonly parent: string;
+    /** The parent state the sub-state exists in. */
+    readonly requires: StateValue;
 }
 /**
- * A typed read-only view over the last applied transition.
- *
- * This view is only meaningful inside transition schedules and is therefore
- * only exposed to systems that explicitly declare transition access.
+ * What `nextMachines.x.set(...)` returns: nothing for a top-level machine,
+ * and for a sub-state a `Result` that fails with `SubStateInactive` when its
+ * parent is in another state.
  */
-export interface TransitionView<M extends StateMachineDefinition = StateMachineDefinition> {
-    get(): TransitionSnapshot<M>;
-}
+export type SetResult<M extends StateMachine.Any> = IsSubState<M> extends true ? Result.Result<void, SubStateInactive> : void;
 /**
- * A typed read-only stream of committed machine transition events.
- *
- * These snapshots are published by `applyStateTransitions(...)` when a
- * transition commits. Like events, each reader sees the transitions published
- * since its own previous run.
+ * The runtime-visible transition payload for one machine. For a sub-state,
+ * `from` is `undefined` when it starts existing (its parent entered its
+ * state) and `to` is `undefined` when it stops.
  */
-export interface TransitionEventView<M extends StateMachineDefinition = StateMachineDefinition> {
-    all(): ReadonlyArray<TransitionSnapshot<M>>;
+export interface TransitionSnapshot<M extends StateMachineDefinition = StateMachineDefinition> {
+    readonly from: CurrentValue<M>;
+    readonly to: CurrentValue<M>;
 }
 /**
  * Read access to the current committed state in a system spec.
@@ -213,12 +222,22 @@ export interface TransitionScheduleDefinition<S extends Schema.Any = Schema.Any,
  * Type-level and value-level helpers for finite-state machines.
  */
 export declare namespace StateMachine {
-    type Any = StateMachineDefinition<string, readonly [StateValue, ...StateValue[]], unknown>;
+    type Any = StateMachineDefinition<string, readonly [StateValue, ...StateValue[]], unknown, unknown>;
     type Value<M extends Any> = M["values"][number];
     type Root<M extends Any> = M extends StateMachineDefinition<string, readonly [StateValue, ...StateValue[]], infer R> ? R : never;
     type AnyCondition<Root = unknown> = Condition<Root>;
     type AnyTransitionSchedule<S extends Schema.Any = Schema.Any, Root = unknown> = TransitionScheduleDefinition<S, Any, Requirement.Requirement, Root, SystemFailure>;
 }
+/**
+ * `unknown` when `M` was defined by the game rooted at `Root`; otherwise a
+ * type naming the fix, so passing another game's machine fails with that
+ * message.
+ */
+export type SameGame<M, Root> = M extends StateMachineDefinition<infer Name, readonly [StateValue, ...StateValue[]], infer MachineRoot> ? [Root] extends [MachineRoot] ? [MachineRoot] extends [Root] ? unknown : ForeignMachine<`${Name} is a state machine of another game: use a machine defined with this game's Game.StateMachine(...)`> : ForeignMachine<`${Name} is a state machine of another game: use a machine defined with this game's Game.StateMachine(...)`> : unknown;
+/** The message type `SameGame` resolves to: a type error prints `Message`. */
+type ForeignMachine<Message extends string> = {
+    readonly __foreignMachine__: Message;
+};
 /** Extracts the machine token from one declared machine access slot. */
 type MachineFromAccess<Access> = Access extends {
     readonly machine: infer M extends StateMachine.Any;
@@ -253,8 +272,11 @@ export type MachineNeedsFromConditions<C extends ReadonlyArray<Condition>> = Mac
  *
  * Use `Descriptor.EntityState(...)` instead when every entity carries its own
  * state (per-entity, written immediately, no enter/exit schedules).
+ *
+ * Pass `within` for a sub-state: a machine that exists only while another
+ * machine is in one state (`Game.StateMachine(name, values, { within })`).
  */
-export declare const StateMachine: <const Name extends string, const Values extends readonly [StateValue, ...StateValue[]], Root = unknown>(name: Name, values: Values) => StateMachineDefinition<Name, Values, Root>;
+export declare const StateMachine: <const Name extends string, const Values extends readonly [StateValue, ...StateValue[]], Root = unknown>(name: Name, values: Values, within?: SubStateParent) => StateMachineDefinition<Name, Values, Root>;
 /**
  * Declares that a system wants to read the current committed state.
  *
@@ -289,7 +311,10 @@ export declare const readTransitionEvent: <M extends StateMachine.Any>(machine:
  */
 export declare const inState: <M extends StateMachine.Any>(machine: M, value: StateMachine.Value<M>) => InStateCondition<M>;
 /**
- * Creates a condition that passes when the machine changed during the current schedule execution.
+ * Creates a condition that passes when the machine changed during the current schedule execution:
+ * from the `applyStateTransitions(...)` that committed the change to the end of
+ * that schedule (or the next `applyStateTransitions(...)`), not for the rest of
+ * the tick call or the next schedule.
  */
 export declare const stateChanged: <M extends StateMachine.Any>(machine: M) => StateChangedCondition<M>;
 /**

package/dist/Machine.d.ts.map

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

package/dist/Machine.js

@@ -14,12 +14,16 @@ import * as Requirement from "./Requirement.js";
  *
  * Use `Descriptor.EntityState(...)` instead when every entity carries its own
  * state (per-entity, written immediately, no enter/exit schedules).
+ *
+ * Pass `within` for a sub-state: a machine that exists only while another
+ * machine is in one state (`Game.StateMachine(name, values, { within })`).
  */
-export const StateMachine = (name, values) => ({
+export const StateMachine = (name, values, within) => ({
     kind: "stateMachine",
     name,
     key: Symbol.for(`ritmo/stateMachine/${name}`),
-    values
+    values,
+    ...(within === undefined ? {} : { within })
 });
 /**
  * Declares that a system wants to read the current committed state.
@@ -68,7 +72,10 @@ export const inState = (machine, value) => ({
     requirements: [machine]
 });
 /**
- * Creates a condition that passes when the machine changed during the current schedule execution.
+ * Creates a condition that passes when the machine changed during the current schedule execution:
+ * from the `applyStateTransitions(...)` that committed the change to the end of
+ * that schedule (or the next `applyStateTransitions(...)`), not for the rest of
+ * the tick call or the next schedule.
  */
 export const stateChanged = (machine) => ({
     kind: "stateChanged",

package/dist/Machine.js.map

@@ -1 +1 @@
-{"version":3,"file":"Machine.js","sourceRoot":"","sources":["../src/Machine.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAqQ/C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAK1B,IAAU,EACV,MAAc,EAC8B,EAAE,CAAC,CAAC;IAChD,IAAI,EAAE,cAAc;IACpB,IAAI;IACJ,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,sBAAsB,IAAI,EAAE,CAAC;IAC7C,MAAM;CACP,CAA+C,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAA6B,OAAU,EAAkB,EAAE,CAAC,CAAC;IAC/E,OAAO;CACR,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAA6B,OAAU,EAAuB,EAAE,CAAC,CAAC;IACrF,OAAO;CACR,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAA6B,OAAU,EAAqB,EAAE,CAAC,CAAC;IACxF,OAAO;CACR,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAA6B,OAAU,EAA0B,EAAE,CAAC,CAAC;IACtG,OAAO;CACR,CAAC,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CACrB,OAAU,EACV,KAA4B,EACP,EAAE,CAAC,CAAC;IACzB,IAAI,EAAE,SAAS;IACf,OAAO;IACP,KAAK;IACL,YAAY,EAAE,CAAC,OAAO,CAAC;CACxB,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,OAAU,EACgB,EAAE,CAAC,CAAC;IAC9B,IAAI,EAAE,cAAc;IACpB,OAAO;IACP,YAAY,EAAE,CAAC,OAAO,CAAC;CACxB,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,CAAsB,SAAY,EAAsC,EAAE,CAAC,CAAC;IAC7F,IAAI,EAAE,KAAK;IACX,SAAS;IACT,YAAY,EAAE,SAAS,CAAC,YAAY;CACrC,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,CAA2C,GAAG,UAAa,EAA8C,EAAE,CAAC,CAAC;IAC9H,IAAI,EAAE,KAAK;IACX,UAAU;IACV,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;CAC7F,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,CAA2C,GAAG,UAAa,EAA6C,EAAE,CAAC,CAAC;IAC5H,IAAI,EAAE,IAAI;IACV,UAAU;IACV,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;CAC7F,CAAC,CAAA"}
+{"version":3,"file":"Machine.js","sourceRoot":"","sources":["../src/Machine.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAkS/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAK1B,IAAU,EACV,MAAc,EACd,MAAuB,EACqB,EAAE,CAAC,CAAC;IAChD,IAAI,EAAE,cAAc;IACpB,IAAI;IACJ,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,sBAAsB,IAAI,EAAE,CAAC;IAC7C,MAAM;IACN,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5C,CAA+C,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAA6B,OAAU,EAAkB,EAAE,CAAC,CAAC;IAC/E,OAAO;CACR,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAA6B,OAAU,EAAuB,EAAE,CAAC,CAAC;IACrF,OAAO;CACR,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAA6B,OAAU,EAAqB,EAAE,CAAC,CAAC;IACxF,OAAO;CACR,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAA6B,OAAU,EAA0B,EAAE,CAAC,CAAC;IACtG,OAAO;CACR,CAAC,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CACrB,OAAU,EACV,KAA4B,EACP,EAAE,CAAC,CAAC;IACzB,IAAI,EAAE,SAAS;IACf,OAAO;IACP,KAAK;IACL,YAAY,EAAE,CAAC,OAAO,CAAC;CACxB,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,OAAU,EACgB,EAAE,CAAC,CAAC;IAC9B,IAAI,EAAE,cAAc;IACpB,OAAO;IACP,YAAY,EAAE,CAAC,OAAO,CAAC;CACxB,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,CAAsB,SAAY,EAAsC,EAAE,CAAC,CAAC;IAC7F,IAAI,EAAE,KAAK;IACX,SAAS;IACT,YAAY,EAAE,SAAS,CAAC,YAAY;CACrC,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,CAA2C,GAAG,UAAa,EAA8C,EAAE,CAAC,CAAC;IAC9H,IAAI,EAAE,KAAK;IACX,UAAU;IACV,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;CAC7F,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,CAA2C,GAAG,UAAa,EAA6C,EAAE,CAAC,CAAC;IAC5H,IAAI,EAAE,IAAI;IACV,UAAU;IACV,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;CAC7F,CAAC,CAAA"}

package/dist/Query.d.ts

@@ -69,6 +69,7 @@
  * Query authoring helpers for selecting components and declaring explicit filters.
  */
 import type { DecodeError } from "./Decode.ts";
+import * as DescriptorModule from "./Descriptor.ts";
 import type { Descriptor, EntityStateValue } from "./Descriptor.ts";
 import type { EntityId, EntityMut, EntityRef } from "./Entity.ts";
 import type * as Result from "./Result.ts";
@@ -163,7 +164,17 @@ export interface ChangedFilter<D extends ComponentDescriptor> {
     readonly kind: "changed";
     readonly descriptor: D;
 }
-export type Filter<D extends ComponentDescriptor> = AddedFilter<D> | ChangedFilter<D>;
+/** An `added` or `changed` filter: the filters `anyOf` combines. */
+export type LifecycleFilter<D extends ComponentDescriptor> = AddedFilter<D> | ChangedFilter<D>;
+/**
+ * A filter that matches entities passing at least one of its `added` /
+ * `changed` filters since the reading system's previous run.
+ */
+export interface AnyOfFilter<D extends ComponentDescriptor> {
+    readonly kind: "anyOf";
+    readonly filters: ReadonlyArray<LifecycleFilter<D>>;
+}
+export type Filter<D extends ComponentDescriptor> = LifecycleFilter<D> | AnyOfFilter<D>;
 /**
  * Declares read-only access to a component in a query selection.
  *
@@ -180,8 +191,21 @@ export declare const read: <D extends ComponentDescriptor>(descriptor: D) => Rea
  * place. A write slot both requires component presence and exposes the slot as
  * a `WriteCell`, so mutation capability stays visible in the query spec rather
  * than appearing ad hoc in the loop body.
+ *
+ * Components declared `immutable: true` cannot be written: replace them with
+ * `commands.insert(...)` instead.
+ */
+export declare const write: <D extends ComponentDescriptor>(descriptor: D & Writable<D>) => WriteAccess<D>;
+type NameOf<D> = D extends {
+    readonly name: infer Name extends string;
+} ? Name : never;
+/**
+ * `unknown` for a component a query may write; for one declared
+ * `immutable: true`, an argument error naming the fix.
  */
-export declare const write: <D extends ComponentDescriptor>(descriptor: D) => WriteAccess<D>;
+export type Writable<D> = D extends DescriptorModule.Immutable ? {
+    readonly __immutable__: `${NameOf<D>} is immutable: replace it with commands.insert(entity, Game.Command.entry(${NameOf<D>}, ...))`;
+} : unknown;
 /**
  * Declares maybe-present read-only access to a component in a query
  * specification.
@@ -230,7 +254,8 @@ export declare const added: <D extends ComponentDescriptor>(descriptor: D) => Ad
  *
  * Any write through a write cell counts, even when the value is equal to the
  * previous one. Writes from a system whose run failed are rolled back and do
- * not count.
+ * not count. A system never sees its own writes as changes on its next run
+ * (it does see the events it emitted).
  *
  * @example
  * ```ts
@@ -243,6 +268,24 @@ export declare const added: <D extends ComponentDescriptor>(descriptor: D) => Ad
  * ```
  */
 export declare const changed: <D extends ComponentDescriptor>(descriptor: D) => ChangedFilter<D>;
+/**
+ * Declares a filter that matches entities passing at least one of `filters`
+ * (`added` / `changed`) since the reading system's previous run. Each entity
+ * is matched once, however many of its filters pass.
+ *
+ * Filters listed side by side in `filters: [...]` must all pass; use `anyOf`
+ * when any one of them is enough, for example to redraw when either the
+ * position or the sprite changed.
+ *
+ * @example
+ * ```ts
+ * const RedrawQuery = Game.Query({
+ *   selection: { position: Game.Query.read(Position), sprite: Game.Query.read(Sprite) },
+ *   filters: [Game.Query.anyOf(Game.Query.changed(Position), Game.Query.changed(Sprite))]
+ * })
+ * ```
+ */
+export declare const anyOf: <const Filters extends readonly [LifecycleFilter<ComponentDescriptor>, LifecycleFilter<ComponentDescriptor>, ...ReadonlyArray<LifecycleFilter<ComponentDescriptor>>]>(...filters: Filters) => AnyOfFilter<Filters[number]["descriptor"]>;
 /**
  * A fully explicit query specification.
  *
@@ -303,6 +346,10 @@ export declare namespace Query {
      * Extracts the schema-root brand carried by one query.
      */
     export type Root<T extends Any> = T extends QuerySpec<any, any, any, any, any, any, any, any, infer R> ? R : never;
+    type FilteredDescriptors<F> = F extends {
+        readonly kind: "added" | "changed";
+        readonly descriptor: infer D;
+    } ? D : never;
     type RequiredSelectionDescriptors<T extends Any> = {
         readonly [K in keyof T["selection"]]: T["selection"][K] extends ReadAccess<infer D> | WriteAccess<infer D> ? D : never;
     }[keyof T["selection"]];
@@ -312,9 +359,15 @@ export declare namespace Query {
      * This is used by durable-handle resolution so intent-qualified handles can
      * only be resolved with queries that actually prove the intended role.
      */
-    export type ProvesComponent<T extends Any, D extends ComponentDescriptor> = [Extract<RequiredSelectionDescriptors<T> | T["with"][number], D>] extends [never] ? false : true;
-    /** The component descriptors a query proves its matches have: required selection slots and `with`. */
-    export type Proven<T extends Any> = RequiredSelectionDescriptors<T> | T["with"][number];
+    export type ProvesComponent<T extends Any, D extends ComponentDescriptor> = [Extract<Proven<T>, D>] extends [never] ? false : true;
+    /**
+     * The component descriptors a query proves its matches have: required
+     * selection slots, `with`, and the component of each `added` / `changed`
+     * filter (a match has it). A `Query.anyOf` member proves nothing alone.
+     */
+    export type Proven<T extends Any> = RequiredSelectionDescriptors<T> | T["with"][number] | FilteredDescriptors<T["filters"][number]>;
+    /** The component descriptors a query proves its matches lack: its `without`. */
+    export type Excluded<T extends Any> = T["without"][number];
     /**
      * The readable proof produced by a query.
      */
@@ -399,13 +452,14 @@ export interface ReadCell<T> {
  */
 export interface WriteCell<T> extends ReadCell<T> {
     /**
-     * Replaces the current value.
+     * Replaces the current value. Takes the readonly shape reads return, so a
+     * value read from any cell can be written back as it is.
      */
-    set(value: T): void;
+    set(value: ReadonlyValue<T>): void;
     /**
      * Updates the current value based on the previous one.
      */
-    update(f: (current: ReadonlyValue<T>) => T): void;
+    update(f: (current: ReadonlyValue<T>) => ReadonlyValue<T>): void;
 }
 /**
  * Writable cell for data backed by a constructed descriptor.
@@ -460,7 +514,10 @@ export interface EntityStateMismatchError<T> {
  */
 export interface EntityStateWriteCell<T, Transitions> extends ConstructedWriteCell<T, T, DecodeError> {
     /**
-     * Moves from `from` to `to` if the component is still in `from`.
+     * Moves from `from` to `to` if the component is still in `from`. Use it for
+     * every move the transition table describes; `set` writes any state
+     * without checking the table, for resets that must not depend on the
+     * current state.
      *
      * @example
      * ```ts
@@ -484,17 +541,24 @@ export type WriteCellForDescriptor<D extends ComponentDescriptor> = D extends im
  */
 export interface PresentOptionalReadCell<T> extends ReadCell<T> {
     readonly present: true;
+    /** The value, which is present. */
+    value(): T;
 }
 /**
  * Absent branch for a maybe-present query slot.
  */
 export interface AbsentOptionalReadCell {
     readonly present: false;
+    /** `undefined`: the entity does not hold the component. */
+    value(): undefined;
 }
 /**
  * A query slot that may or may not be present on the matched entity.
  *
- * Callers must narrow on `present` before reading the value.
+ * Read it with `value()`: the value, or `undefined` when the entity does not
+ * hold the component. Narrow on `present` (then `get()`) only when the
+ * component's own value can be `undefined`, where `value()` cannot tell the
+ * two apart.
  */
 export type OptionalReadCell<T> = PresentOptionalReadCell<T> | AbsentOptionalReadCell;
 /**
@@ -504,10 +568,10 @@ export type OptionalReadCell<T> = PresentOptionalReadCell<T> | AbsentOptionalRea
  * Otherwise it remains read-only.
  */
 export type QueryMatch<S extends Schema.Any, Q extends Query.Any> = keyof Query.WriteProof<Q> extends never ? {
-    readonly entity: EntityRef<S, Query.ReadProof<Q>, Query.Root<Q>, Query.Proven<Q>>;
+    readonly entity: EntityRef<S, Query.ReadProof<Q>, Query.Root<Q>, Query.Proven<Q>, Query.Excluded<Q>>;
     readonly data: Query.Cells<Q>;
 } : {
-    readonly entity: EntityMut<S, Query.ReadProof<Q>, Query.WriteProof<Q>, Query.Root<Q>, Query.Proven<Q>>;
+    readonly entity: EntityMut<S, Query.ReadProof<Q>, Query.WriteProof<Q>, Query.Root<Q>, Query.Proven<Q>, Query.Excluded<Q>>;
     readonly data: Query.Cells<Q>;
 };
 /**
@@ -556,10 +620,32 @@ export declare const multipleEntitiesError: (count: number) => Query.MultipleEnt
  * (`queries: { ... }` in a spec). Unlike `NoInfer`, it prints as `T`.
  */
 export type Uninferred<T, Bound> = [T] extends [infer U extends Bound] ? U : never;
+type DescriptorName<D> = D extends {
+    readonly name: infer Name extends string;
+} ? Name : never;
+/** The names a query requires: its read and write slots, `with`, and plain `added` / `changed` filters. */
+type RequiredNames<Selection, With extends ReadonlyArray<unknown>, Filters extends ReadonlyArray<unknown>> = DescriptorName<{
+    readonly [K in keyof Selection]: Selection[K] extends {
+        readonly mode: "read" | "write";
+        readonly descriptor: infer D;
+    } ? D : never;
+}[keyof Selection]> | DescriptorName<With[number]> | DescriptorName<Filters[number] extends infer F ? F extends {
+    readonly kind: "added" | "changed";
+    readonly descriptor: infer D;
+} ? D : never : never>;
+/**
+ * Rejects a `without` naming a component the query also requires: such a
+ * query can never match. Use it on the `without` list of a query spec.
+ */
+export type ExclusionsPossible<Selection, With extends ReadonlyArray<unknown>, Without extends ReadonlyArray<unknown>, Filters extends ReadonlyArray<unknown>> = [
+    Extract<DescriptorName<Without[number]>, RequiredNames<Selection, With, Filters>>
+] extends [never] ? unknown : {
+    readonly __fixQuery__: `${Extract<DescriptorName<Without[number]>, RequiredNames<Selection, With, Filters>>} is both required and excluded (without): this query can never match; remove it from one side`;
+};
 export declare const Query: <const Selection extends Record<string, SelectionAccess<any, Root>>, const With extends ReadonlyArray<ComponentDescriptor> = [], const Without extends ReadonlyArray<ComponentDescriptor> = [], const Filters extends ReadonlyArray<Filter<ComponentDescriptor>> = [], const WithRelations extends ReadonlyArray<Relation.Relation.Any> = [], const WithoutRelations extends ReadonlyArray<Relation.Relation.Any> = [], const WithRelated extends ReadonlyArray<Relation.Relation.Any> = [], const WithoutRelated extends ReadonlyArray<Relation.Relation.Any> = [], Root = unknown>(spec: {
     readonly selection: Selection;
     readonly with?: With;
-    readonly without?: Without;
+    readonly without?: Without & ExclusionsPossible<Selection, With, Without, Filters>;
     readonly filters?: Filters;
     readonly withRelations?: WithRelations;
     readonly withoutRelations?: WithoutRelations;