koota-kit 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.6.0](https://github.com/jbcom/koota-kit/compare/v0.5.0...v0.6.0) (2026-10-10)
+
+
+### Features
+
+* **schedule:** add createSchedule, a fixed-step system schedule ([bb69bd6](https://github.com/jbcom/koota-kit/commit/bb69bd638e7a3dc6315ede827e4c58820facea3a))
+* **schedule:** add createSchedule, a fixed-step system schedule ([21f6ffb](https://github.com/jbcom/koota-kit/commit/21f6ffbb2a6f4fae819f88197d02e30f50cc98ea))
+
+
+### Bug Fixes
+
+* **schedule:** pause means no steps, and a refused step is never debited ([e2fbfad](https://github.com/jbcom/koota-kit/commit/e2fbfadb363764bc8c43232e19862223ef250ee6))
+
+## [0.5.0](https://github.com/jbcom/koota-kit/compare/v0.4.0...v0.5.0) (2026-10-10)
+
+
+### Features
+
+* **react:** add koota-kit/react with SimWorldProvider and useSimWorld ([3a9aeee](https://github.com/jbcom/koota-kit/commit/3a9aeee17d67af90bb8be925fd123bfba32f2968))
+* **react:** add koota-kit/react with SimWorldProvider and useSimWorld ([74a5f1c](https://github.com/jbcom/koota-kit/commit/74a5f1c683246797dfa60010375a3a4f6333d37c))
+
 ## [0.4.0](https://github.com/jbcom/koota-kit/compare/v0.3.1...v0.4.0) (2026-10-08)
 
 

package/README.md

@@ -38,6 +38,8 @@ Requirements:
   The package declares `>=22`; support follows maintained Node lines rather
   than requiring one exact patch release.
 - Koota `^0.6.6`, installed by the application as a peer dependency
+- React `>=18`, only if you import `koota-kit/react`; it is an optional peer
+  dependency, and no other entry point loads it
 
 The package ships native ESM and CommonJS entry points with format-correct
 TypeScript declarations.
@@ -135,6 +137,26 @@ defineTrait({ storage: { logs: 0 } });         // TypeError: shared object footg
 Declare traits once in a leaf module and export each trait from one location.
 Koota identifies traits by reference, not by a string name.
 
+### A fixed-step schedule removes the frame rate from the sim
+
+`createSchedule(systems, { step, maxSteps })` returns a `tick(handle, frameDt)`
+for your frame loop. The frame's dt fills an accumulator kept in `handle.scratch`
+(so it dies with the run); each whole `step` advances the clock, then calls every
+system in order with `dt === step`. At most `maxSteps` run per tick and any
+excess is dropped, so one huge dt after a backgrounded tab cannot cause a
+catch-up storm. `tick(handle, 0)` is a valid pause and returns the steps run.
+
+```ts
+import { createSchedule } from "koota-kit";
+
+const schedule = createSchedule([stove, mixer, serving], { step: 1 / 60, maxSteps: 6 });
+// once per rendered frame:
+const steps = schedule.tick(sim, frameDt);
+```
+
+Sixty frames of 1/60 s and thirty of 1/30 s run the same sixty steps.
+`schedule.remainder(sim) / schedule.step` is the interpolation alpha.
+
 ### Event logs have one consuming owner
 
 `push` appends, `drain` returns every pending event and empties the log, and
@@ -154,9 +176,48 @@ and restores atomically.
 Persist a version beside the header and your ECS state so the application can
 migrate its own schema.
 
+## React
+
+`koota/react` hooks reach only the Koota `World`. `koota-kit/react` adds a
+provider for the whole `WorldHandle`, so components can also reach its RNG
+streams, seeds, clock and scratch:
+
+```tsx
+import { useQuery } from "koota/react";
+import { createSimWorld, defineTrait, nextInt } from "koota-kit";
+import { SimWorldProvider, useSimWorld } from "koota-kit/react";
+
+const Position = defineTrait({ x: 0, y: 0 });
+const handle = createSimWorld({ gen: "world-7", events: "run-7" });
+
+function Scouts() {
+  const { rng } = useSimWorld(); // the handle: rng, seeds, clock, scratch
+  const scouts = useQuery(Position); // koota/react hooks share the same provider
+  return (
+    <button type="button" onClick={() => nextInt(rng.events, 1, 7)}>
+      Roll for {scouts.length} scouts
+    </button>
+  );
+}
+
+root.render(
+  <SimWorldProvider handle={handle}>
+    <Scouts />
+  </SimWorldProvider>,
+);
+```
+
+`SimWorldProvider` renders Koota's own `WorldProvider` for `handle.world`, so
+`useTrait`, `useQuery` and `useActions` need no second provider. `useSimWorld()`
+throws outside a provider. Passing a different `handle` re-provides every
+consumer; the provider does not create or destroy the handle, so pair
+`createSimWorld` with `destroySimWorld` yourself.
+
 ## API and architecture
 
-The root package exports the full API. Focused entry points are also available:
+The root package exports the full API except the React bindings, which live
+only at `koota-kit/react` so the root never loads React. Focused entry points
+are also available:
 
 | Entry point | Purpose |
 | --- | --- |
@@ -164,7 +225,9 @@ The root package exports the full API. Focused entry points are also available:
 | `koota-kit/rng` | Seeded streams, named substreams, bounded draws, snapshots |
 | `koota-kit/seed` | Seed derivation and 128-bit master seeds |
 | `koota-kit/traits` | Safe trait declaration |
+| `koota-kit/schedule` | Fixed-step system schedule with a step cap |
 | `koota-kit/eventLog` | World-scoped publish/drain logs |
+| `koota-kit/react` | `SimWorldProvider` and `useSimWorld` (optional React peer) |
 
 See the [API reference](./docs/API.md) for signatures and validation behavior,
 and [architecture notes](./docs/ARCHITECTURE.md) for module boundaries and
@@ -182,6 +245,8 @@ For task-oriented usage, read the Sourcey guides on
 - `createMasterSeed` throws when no entropy source exists or the source leaves
   the buffer all zero.
 - `advanceClock` accepts finite, non-negative `dt`; `0` is a valid paused tick.
+- `createSchedule` needs a finite `step > 0` and a safe-integer `maxSteps >= 1`;
+  a negative, `NaN` or infinite `frameDt` counts as `0`.
 - `nextInt` requires safe-integer bounds with `maxExclusive > minInclusive` and
   a range no larger than `2**32`.
 - `chance` accepts only finite probabilities in `[0, 1]`.

package/dist/cjs/index.cjs

@@ -1,8 +1,9 @@
 "use strict";
 // koota-kit — thin koota ECS conventions layer.
 //
-// Five modules, also importable as subpaths:
+// Six modules, also importable as subpaths:
 //   ./world    — WorldHandle lifecycle (world + dual-stream rng + clock + scratch)
+//   ./schedule — fixed-step system schedule (accumulator in scratch, step cap)
 //   ./rng      — dual-layer deterministic seedrandom PRNG and named substreams
 //                with byte-exact snapshot/restore
 //   ./seed     — length-prefixed SHA-256 seed derivation and 128-bit master
@@ -12,7 +13,7 @@
 //   ./eventLog — scratch-backed publish/drain event logs with a peek seam for
 //                observers (harnesses, tests, HUDs)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineTrait = exports.defineEventLog = exports.MASTER_SEED_BYTES = exports.isMasterSeed = exports.deriveSeed = exports.createMasterSeed = exports.substream = exports.snapshotSubstreams = exports.snapshotStream = exports.snapshotLayers = exports.shuffle = exports.restoreSubstreams = exports.restoreStream = exports.restoreLayers = exports.pick = exports.nextU32 = exports.nextInt = exports.nextFloat = exports.getSubstream = exports.createSubstreams = exports.createRng = exports.chance = exports.trait = exports.snapshotWorld = exports.restoreWorldHeader = exports.relation = exports.destroySimWorld = exports.createSimWorld = exports.createActions = exports.advanceClock = void 0;
+exports.defineTrait = exports.defineEventLog = exports.createSchedule = exports.MASTER_SEED_BYTES = exports.isMasterSeed = exports.deriveSeed = exports.createMasterSeed = exports.substream = exports.snapshotSubstreams = exports.snapshotStream = exports.snapshotLayers = exports.shuffle = exports.restoreSubstreams = exports.restoreStream = exports.restoreLayers = exports.pick = exports.nextU32 = exports.nextInt = exports.nextFloat = exports.getSubstream = exports.createSubstreams = exports.createRng = exports.chance = exports.trait = exports.snapshotWorld = exports.restoreWorldHeader = exports.relation = exports.destroySimWorld = exports.createSimWorld = exports.createActions = exports.advanceClock = void 0;
 var world_js_1 = require("./world.cjs");
 Object.defineProperty(exports, "advanceClock", { enumerable: true, get: function () { return world_js_1.advanceClock; } });
 Object.defineProperty(exports, "createActions", { enumerable: true, get: function () { return world_js_1.createActions; } });
@@ -44,6 +45,8 @@ Object.defineProperty(exports, "createMasterSeed", { enumerable: true, get: func
 Object.defineProperty(exports, "deriveSeed", { enumerable: true, get: function () { return seed_js_1.deriveSeed; } });
 Object.defineProperty(exports, "isMasterSeed", { enumerable: true, get: function () { return seed_js_1.isMasterSeed; } });
 Object.defineProperty(exports, "MASTER_SEED_BYTES", { enumerable: true, get: function () { return seed_js_1.MASTER_SEED_BYTES; } });
+var schedule_js_1 = require("./schedule.cjs");
+Object.defineProperty(exports, "createSchedule", { enumerable: true, get: function () { return schedule_js_1.createSchedule; } });
 var eventLog_js_1 = require("./eventLog.cjs");
 Object.defineProperty(exports, "defineEventLog", { enumerable: true, get: function () { return eventLog_js_1.defineEventLog; } });
 var index_js_1 = require("./traits/index.cjs");

package/dist/cjs/index.d.cts

@@ -4,6 +4,8 @@ export { chance, createRng, createSubstreams, getSubstream, nextFloat, nextInt,
 export type { RngLayers, RngLayersSnapshot, RngSeeds, RngStream, RngStreamSnapshot, Substreams, SubstreamsSnapshot, } from "./rng.cjs";
 export { createMasterSeed, deriveSeed, isMasterSeed, MASTER_SEED_BYTES } from "./seed.cjs";
 export type { EntropySource, SeedPart } from "./seed.cjs";
+export { createSchedule } from "./schedule.cjs";
+export type { Schedule, ScheduleOptions, System } from "./schedule.cjs";
 export { defineEventLog } from "./eventLog.cjs";
 export type { EventLog } from "./eventLog.cjs";
 export { defineTrait } from "./traits/index.cjs";

package/dist/cjs/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,OAAO,EACP,OAAO,EACP,IAAI,EACJ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC1F,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,OAAO,EACP,OAAO,EACP,IAAI,EACJ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC1F,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/cjs/react.cjs

@@ -0,0 +1,39 @@
+"use strict";
+// React bindings for the sim handle. This is the ONLY module that imports
+// React (through koota/react), and nothing else in the package imports it, so
+// the root entry and every other subpath stay React-free. `react` is an
+// optional peer dependency: consumers who never import `koota-kit/react` never
+// need it installed.
+//
+// koota/react's own `WorldProvider` / `useWorld` carry only the koota `World`.
+// A component that needs the handle's RNG streams, seeds, clock or scratch
+// cannot reach them from there. `SimWorldProvider` supplies the whole
+// `WorldHandle` AND mounts koota's provider for `handle.world`, so
+// `useTrait`, `useQuery` and `useActions` work underneath it unchanged.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimWorldProvider = void 0;
+exports.useSimWorld = useSimWorld;
+const react_1 = require("koota/react");
+const react_2 = require("react");
+const SimWorldContext = (0, react_2.createContext)(null);
+SimWorldContext.displayName = "SimWorldContext";
+/**
+ * Provide a `WorldHandle` to the tree below. Renders koota's `WorldProvider`
+ * for `handle.world`, so every `koota/react` hook works under it without a
+ * second provider. The provider does not own the handle's lifecycle: create it
+ * with `createSimWorld` and release it with `destroySimWorld` yourself.
+ */
+const SimWorldProvider = ({ handle, children }) => (0, react_2.createElement)(SimWorldContext.Provider, { value: handle }, (0, react_2.createElement)(react_1.WorldProvider, { world: handle.world, children }));
+exports.SimWorldProvider = SimWorldProvider;
+/**
+ * The `WorldHandle` provided by the nearest `SimWorldProvider`: its `world`,
+ * `rng`, `seeds`, `clock` and `scratch`. Throws when called outside one — a
+ * missing provider is a wiring bug, not a state to render around.
+ */
+function useSimWorld() {
+    const handle = (0, react_2.useContext)(SimWorldContext);
+    if (handle === null) {
+        throw new Error("useSimWorld must be used within a <SimWorldProvider>");
+    }
+    return handle;
+}

package/dist/cjs/react.d.cts

@@ -0,0 +1,21 @@
+import type { FunctionComponent, ReactNode } from "react";
+import type { WorldHandle } from "./world.cjs";
+export type SimWorldProviderProps = {
+    /** The handle from `createSimWorld`. Swapping it re-provides every consumer. */
+    readonly handle: WorldHandle;
+    readonly children?: ReactNode;
+};
+/**
+ * Provide a `WorldHandle` to the tree below. Renders koota's `WorldProvider`
+ * for `handle.world`, so every `koota/react` hook works under it without a
+ * second provider. The provider does not own the handle's lifecycle: create it
+ * with `createSimWorld` and release it with `destroySimWorld` yourself.
+ */
+export declare const SimWorldProvider: FunctionComponent<SimWorldProviderProps>;
+/**
+ * The `WorldHandle` provided by the nearest `SimWorldProvider`: its `world`,
+ * `rng`, `seeds`, `clock` and `scratch`. Throws when called outside one — a
+ * missing provider is a wiring bug, not a state to render around.
+ */
+export declare function useSimWorld(): WorldHandle;
+//# sourceMappingURL=react.d.cts.map

package/dist/cjs/react.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../src/react.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;CAC/B,CAAC;AAKF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAAiB,CAAC,qBAAqB,CAKnE,CAAC;AAEJ;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,WAAW,CAMzC"}

package/dist/cjs/schedule.cjs

@@ -0,0 +1,131 @@
+"use strict";
+// Fixed-step system schedule — the loop that turns "a frame passed" into
+// "the sim advanced by whole steps".
+//
+// A simulation that integrates the frame's own dt drifts with the frame rate:
+// a 120 Hz phone and a test that advances three seconds in one call disagree,
+// and anything counted in real time (a save every 0.25 s) lands on different
+// ticks. A fixed-step schedule removes the frame rate from the sim: the frame's
+// dt fills an accumulator, and the sim only ever advances by whole `step`s.
+//
+// The loop is generic sim plumbing, so it lives here and not in the game: it
+// knows nothing about React, a renderer, or what a system does. A renderer's
+// frame callback calls `schedule.tick(handle, dt)` and that is the entire
+// integration. The accumulator lives in the handle's `scratch`, so it dies with
+// the run: a new world starts with nothing owed, and two schedules (or two
+// worlds) never share one.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSchedule = createSchedule;
+const world_js_1 = require("./world.cjs");
+let nextScheduleId = 0;
+// Keys are process-wide because schedules are declared once at module scope and
+// used on many handles. An explicit key may be shared on purpose; a generated
+// one must stay private to its schedule.
+const claimedKeys = new Set();
+const generatedKeys = new Set();
+// Float accumulation: 432 frames of 1/144 add up to a hair under 3 s, and
+// without a tolerance the sim would owe — and run — one step fewer than the
+// same time delivered at 60 Hz. A billionth of a step is far below anything a
+// frame clock can resolve, so treating "within it" as whole costs nothing.
+const STEP_TOLERANCE = 1e-9;
+/**
+ * Build a fixed-step schedule over `systems`, run in the order given.
+ *
+ * ```ts
+ * const schedule = createSchedule([intro, stove, mixer, serving], {
+ *   step: 1 / 60,
+ *   maxSteps: 6,
+ * });
+ * // once per rendered frame, with the frame's dt:
+ * schedule.tick(run, frameDt);
+ * ```
+ *
+ * The systems array is copied; later changes to it do not affect the schedule.
+ */
+function createSchedule(systems, options) {
+    if (!Array.isArray(systems)) {
+        throw new TypeError("createSchedule: systems must be an array of functions.");
+    }
+    const { step, maxSteps } = options;
+    if (!Number.isFinite(step) || step <= 0) {
+        throw new RangeError(`createSchedule: step must be finite and greater than zero; received ${step}.`);
+    }
+    if (!Number.isSafeInteger(maxSteps) || maxSteps < 1) {
+        throw new RangeError(`createSchedule: maxSteps must be a safe integer of at least 1; received ${maxSteps}.`);
+    }
+    if (options.key !== undefined && (typeof options.key !== "string" || options.key === "")) {
+        throw new TypeError("createSchedule: key must be a non-empty string when provided.");
+    }
+    const ordered = Object.freeze([...systems]);
+    for (const system of ordered) {
+        if (typeof system !== "function") {
+            throw new TypeError("createSchedule: every system must be a function.");
+        }
+    }
+    let key;
+    if (options.key === undefined) {
+        // Skip any key a caller has already named, so a default never lands on one.
+        do {
+            key = `schedule:${nextScheduleId++}`;
+        } while (claimedKeys.has(key));
+        generatedKeys.add(key);
+    }
+    else {
+        if (generatedKeys.has(options.key)) {
+            throw new TypeError(`createSchedule: key "${options.key}" is already the generated key of another schedule.`);
+        }
+        key = options.key;
+    }
+    claimedKeys.add(key);
+    const tolerance = step * STEP_TOLERANCE;
+    function read(handle) {
+        const stored = handle.scratch.get(key);
+        if (stored === undefined)
+            return 0;
+        if (typeof stored !== "number" || !Number.isFinite(stored) || stored < 0) {
+            throw new TypeError(`createSchedule: scratch key "${key}" already holds something other than a schedule accumulator.`);
+        }
+        return stored;
+    }
+    function tick(handle, frameDt) {
+        const previous = read(handle);
+        // A pause (and any frame dt that counts as 0) runs nothing, even if a
+        // failed tick left whole steps owed: those wait for a frame that moves time.
+        if (!(Number.isFinite(frameDt) && frameDt > 0))
+            return 0;
+        const sum = previous + frameDt;
+        // Two huge finite frames can sum past the double range; saturate instead of
+        // letting Infinity poison the stored accumulator.
+        let owed = Number.isFinite(sum) ? sum : Number.MAX_VALUE;
+        let ran = 0;
+        try {
+            while (owed + tolerance >= step && ran < maxSteps) {
+                // The clock moves first, so a step it refuses (an exhausted clock) is
+                // never debited. After that the step is spent before any system runs:
+                // if one throws, this step's time is gone with the tick it caused.
+                (0, world_js_1.advanceClock)(handle, step);
+                owed = Math.max(0, owed - step);
+                ran++;
+                for (const system of ordered)
+                    system(handle, step);
+            }
+            if (owed + tolerance >= step) {
+                // Capped with whole steps still owed: drop them, keep the fraction.
+                owed %= step;
+                if (owed + tolerance >= step)
+                    owed = 0;
+            }
+        }
+        finally {
+            handle.scratch.set(key, owed);
+        }
+        return ran;
+    }
+    return Object.freeze({
+        step,
+        maxSteps,
+        key,
+        tick,
+        remainder: read,
+    });
+}

package/dist/cjs/schedule.d.cts

@@ -0,0 +1,69 @@
+import type { WorldHandle } from "./world.cjs";
+/**
+ * One unit of sim work, run once per fixed step.
+ *
+ * `dt` is always the schedule's `step`, never the frame's dt, so a system can
+ * integrate it without knowing the frame rate. Systems that need randomness
+ * should draw from a named substream rather than the handle's positional `rng`,
+ * so adding a system does not shift another system's draws.
+ */
+export type System = (handle: WorldHandle, dt: number) => void;
+export type ScheduleOptions = {
+    /** Seconds of sim time one step represents. Finite and greater than zero. */
+    step: number;
+    /**
+     * The most steps a single `tick` may run. A safe integer of at least 1. Time
+     * owed beyond this is dropped, not carried, so one huge frame dt (a hidden
+     * tab returning after a minute) cannot trigger a catch-up storm.
+     */
+    maxSteps: number;
+    /**
+     * The `scratch` key holding this schedule's accumulator, for callers who want
+     * to namespace it (`"run:schedule"`). Defaults to a key unique to this
+     * schedule. Two schedules given the same key share one accumulator.
+     */
+    key?: string;
+};
+export type Schedule = {
+    readonly step: number;
+    readonly maxSteps: number;
+    /** The `scratch` key holding this schedule's accumulator on a handle. */
+    readonly key: string;
+    /**
+     * Add `frameDt` seconds to `handle`'s accumulator and run every whole step it
+     * now covers, up to `maxSteps`: each step advances the clock by `step`, then
+     * calls every system in order with `dt === step`. Returns how many steps ran.
+     *
+     * A `frameDt` that is negative, `NaN` or infinite counts as `0`, and `0` is a
+     * valid pause: no step runs and the clock does not move. Whole steps beyond
+     * `maxSteps` are dropped; the sub-step remainder is kept.
+     *
+     * If a system throws, the steps that had already started are consumed (the
+     * clock moved for them) and the rest stay owed, so a retry does not replay
+     * time the sim already spent.
+     */
+    tick: (handle: WorldHandle, frameDt: number) => number;
+    /**
+     * Seconds currently owed to the next step, in `[0, step)` between ticks.
+     * Dividing it by `step` gives the interpolation alpha for a renderer drawing
+     * between the previous and current sim state. `0` on a handle that has not
+     * ticked.
+     */
+    remainder: (handle: WorldHandle) => number;
+};
+/**
+ * Build a fixed-step schedule over `systems`, run in the order given.
+ *
+ * ```ts
+ * const schedule = createSchedule([intro, stove, mixer, serving], {
+ *   step: 1 / 60,
+ *   maxSteps: 6,
+ * });
+ * // once per rendered frame, with the frame's dt:
+ * schedule.tick(run, frameDt);
+ * ```
+ *
+ * The systems array is copied; later changes to it do not affect the schedule.
+ */
+export declare function createSchedule(systems: readonly System[], options: ScheduleOptions): Readonly<Schedule>;
+//# sourceMappingURL=schedule.d.cts.map

package/dist/cjs/schedule.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/schedule.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;AAE/D,MAAM,MAAM,eAAe,GAAG;IAC5B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACvD;;;;;OAKG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,MAAM,CAAC;CAC5C,CAAC;AAeF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,eAAe,GACvB,QAAQ,CAAC,QAAQ,CAAC,CA2FpB"}

package/dist/esm/index.d.ts

@@ -4,6 +4,8 @@ export { chance, createRng, createSubstreams, getSubstream, nextFloat, nextInt,
 export type { RngLayers, RngLayersSnapshot, RngSeeds, RngStream, RngStreamSnapshot, Substreams, SubstreamsSnapshot, } from "./rng.js";
 export { createMasterSeed, deriveSeed, isMasterSeed, MASTER_SEED_BYTES } from "./seed.js";
 export type { EntropySource, SeedPart } from "./seed.js";
+export { createSchedule } from "./schedule.js";
+export type { Schedule, ScheduleOptions, System } from "./schedule.js";
 export { defineEventLog } from "./eventLog.js";
 export type { EventLog } from "./eventLog.js";
 export { defineTrait } from "./traits/index.js";

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,OAAO,EACP,OAAO,EACP,IAAI,EACJ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC1F,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,OAAO,EACP,OAAO,EACP,IAAI,EACJ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC1F,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/esm/index.js

@@ -1,7 +1,8 @@
 // koota-kit — thin koota ECS conventions layer.
 //
-// Five modules, also importable as subpaths:
+// Six modules, also importable as subpaths:
 //   ./world    — WorldHandle lifecycle (world + dual-stream rng + clock + scratch)
+//   ./schedule — fixed-step system schedule (accumulator in scratch, step cap)
 //   ./rng      — dual-layer deterministic seedrandom PRNG and named substreams
 //                with byte-exact snapshot/restore
 //   ./seed     — length-prefixed SHA-256 seed derivation and 128-bit master
@@ -13,5 +14,6 @@
 export { advanceClock, createActions, createSimWorld, destroySimWorld, relation, restoreWorldHeader, snapshotWorld, trait, } from "./world.js";
 export { chance, createRng, createSubstreams, getSubstream, nextFloat, nextInt, nextU32, pick, restoreLayers, restoreStream, restoreSubstreams, shuffle, snapshotLayers, snapshotStream, snapshotSubstreams, substream, } from "./rng.js";
 export { createMasterSeed, deriveSeed, isMasterSeed, MASTER_SEED_BYTES } from "./seed.js";
+export { createSchedule } from "./schedule.js";
 export { defineEventLog } from "./eventLog.js";
 export { defineTrait } from "./traits/index.js";

package/dist/esm/react.d.ts

@@ -0,0 +1,21 @@
+import type { FunctionComponent, ReactNode } from "react";
+import type { WorldHandle } from "./world.js";
+export type SimWorldProviderProps = {
+    /** The handle from `createSimWorld`. Swapping it re-provides every consumer. */
+    readonly handle: WorldHandle;
+    readonly children?: ReactNode;
+};
+/**
+ * Provide a `WorldHandle` to the tree below. Renders koota's `WorldProvider`
+ * for `handle.world`, so every `koota/react` hook works under it without a
+ * second provider. The provider does not own the handle's lifecycle: create it
+ * with `createSimWorld` and release it with `destroySimWorld` yourself.
+ */
+export declare const SimWorldProvider: FunctionComponent<SimWorldProviderProps>;
+/**
+ * The `WorldHandle` provided by the nearest `SimWorldProvider`: its `world`,
+ * `rng`, `seeds`, `clock` and `scratch`. Throws when called outside one — a
+ * missing provider is a wiring bug, not a state to render around.
+ */
+export declare function useSimWorld(): WorldHandle;
+//# sourceMappingURL=react.d.ts.map

package/dist/esm/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../src/react.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;CAC/B,CAAC;AAKF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAAiB,CAAC,qBAAqB,CAKnE,CAAC;AAEJ;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,WAAW,CAMzC"}

package/dist/esm/react.js

@@ -0,0 +1,34 @@
+// React bindings for the sim handle. This is the ONLY module that imports
+// React (through koota/react), and nothing else in the package imports it, so
+// the root entry and every other subpath stay React-free. `react` is an
+// optional peer dependency: consumers who never import `koota-kit/react` never
+// need it installed.
+//
+// koota/react's own `WorldProvider` / `useWorld` carry only the koota `World`.
+// A component that needs the handle's RNG streams, seeds, clock or scratch
+// cannot reach them from there. `SimWorldProvider` supplies the whole
+// `WorldHandle` AND mounts koota's provider for `handle.world`, so
+// `useTrait`, `useQuery` and `useActions` work underneath it unchanged.
+import { WorldProvider } from "koota/react";
+import { createContext, createElement, useContext } from "react";
+const SimWorldContext = createContext(null);
+SimWorldContext.displayName = "SimWorldContext";
+/**
+ * Provide a `WorldHandle` to the tree below. Renders koota's `WorldProvider`
+ * for `handle.world`, so every `koota/react` hook works under it without a
+ * second provider. The provider does not own the handle's lifecycle: create it
+ * with `createSimWorld` and release it with `destroySimWorld` yourself.
+ */
+export const SimWorldProvider = ({ handle, children }) => createElement(SimWorldContext.Provider, { value: handle }, createElement(WorldProvider, { world: handle.world, children }));
+/**
+ * The `WorldHandle` provided by the nearest `SimWorldProvider`: its `world`,
+ * `rng`, `seeds`, `clock` and `scratch`. Throws when called outside one — a
+ * missing provider is a wiring bug, not a state to render around.
+ */
+export function useSimWorld() {
+    const handle = useContext(SimWorldContext);
+    if (handle === null) {
+        throw new Error("useSimWorld must be used within a <SimWorldProvider>");
+    }
+    return handle;
+}

package/dist/esm/schedule.d.ts

@@ -0,0 +1,69 @@
+import type { WorldHandle } from "./world.js";
+/**
+ * One unit of sim work, run once per fixed step.
+ *
+ * `dt` is always the schedule's `step`, never the frame's dt, so a system can
+ * integrate it without knowing the frame rate. Systems that need randomness
+ * should draw from a named substream rather than the handle's positional `rng`,
+ * so adding a system does not shift another system's draws.
+ */
+export type System = (handle: WorldHandle, dt: number) => void;
+export type ScheduleOptions = {
+    /** Seconds of sim time one step represents. Finite and greater than zero. */
+    step: number;
+    /**
+     * The most steps a single `tick` may run. A safe integer of at least 1. Time
+     * owed beyond this is dropped, not carried, so one huge frame dt (a hidden
+     * tab returning after a minute) cannot trigger a catch-up storm.
+     */
+    maxSteps: number;
+    /**
+     * The `scratch` key holding this schedule's accumulator, for callers who want
+     * to namespace it (`"run:schedule"`). Defaults to a key unique to this
+     * schedule. Two schedules given the same key share one accumulator.
+     */
+    key?: string;
+};
+export type Schedule = {
+    readonly step: number;
+    readonly maxSteps: number;
+    /** The `scratch` key holding this schedule's accumulator on a handle. */
+    readonly key: string;
+    /**
+     * Add `frameDt` seconds to `handle`'s accumulator and run every whole step it
+     * now covers, up to `maxSteps`: each step advances the clock by `step`, then
+     * calls every system in order with `dt === step`. Returns how many steps ran.
+     *
+     * A `frameDt` that is negative, `NaN` or infinite counts as `0`, and `0` is a
+     * valid pause: no step runs and the clock does not move. Whole steps beyond
+     * `maxSteps` are dropped; the sub-step remainder is kept.
+     *
+     * If a system throws, the steps that had already started are consumed (the
+     * clock moved for them) and the rest stay owed, so a retry does not replay
+     * time the sim already spent.
+     */
+    tick: (handle: WorldHandle, frameDt: number) => number;
+    /**
+     * Seconds currently owed to the next step, in `[0, step)` between ticks.
+     * Dividing it by `step` gives the interpolation alpha for a renderer drawing
+     * between the previous and current sim state. `0` on a handle that has not
+     * ticked.
+     */
+    remainder: (handle: WorldHandle) => number;
+};
+/**
+ * Build a fixed-step schedule over `systems`, run in the order given.
+ *
+ * ```ts
+ * const schedule = createSchedule([intro, stove, mixer, serving], {
+ *   step: 1 / 60,
+ *   maxSteps: 6,
+ * });
+ * // once per rendered frame, with the frame's dt:
+ * schedule.tick(run, frameDt);
+ * ```
+ *
+ * The systems array is copied; later changes to it do not affect the schedule.
+ */
+export declare function createSchedule(systems: readonly System[], options: ScheduleOptions): Readonly<Schedule>;
+//# sourceMappingURL=schedule.d.ts.map

package/dist/esm/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/schedule.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;AAE/D,MAAM,MAAM,eAAe,GAAG;IAC5B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACvD;;;;;OAKG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,MAAM,CAAC;CAC5C,CAAC;AAeF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,eAAe,GACvB,QAAQ,CAAC,QAAQ,CAAC,CA2FpB"}

package/dist/esm/schedule.js

@@ -0,0 +1,128 @@
+// Fixed-step system schedule — the loop that turns "a frame passed" into
+// "the sim advanced by whole steps".
+//
+// A simulation that integrates the frame's own dt drifts with the frame rate:
+// a 120 Hz phone and a test that advances three seconds in one call disagree,
+// and anything counted in real time (a save every 0.25 s) lands on different
+// ticks. A fixed-step schedule removes the frame rate from the sim: the frame's
+// dt fills an accumulator, and the sim only ever advances by whole `step`s.
+//
+// The loop is generic sim plumbing, so it lives here and not in the game: it
+// knows nothing about React, a renderer, or what a system does. A renderer's
+// frame callback calls `schedule.tick(handle, dt)` and that is the entire
+// integration. The accumulator lives in the handle's `scratch`, so it dies with
+// the run: a new world starts with nothing owed, and two schedules (or two
+// worlds) never share one.
+import { advanceClock } from "./world.js";
+let nextScheduleId = 0;
+// Keys are process-wide because schedules are declared once at module scope and
+// used on many handles. An explicit key may be shared on purpose; a generated
+// one must stay private to its schedule.
+const claimedKeys = new Set();
+const generatedKeys = new Set();
+// Float accumulation: 432 frames of 1/144 add up to a hair under 3 s, and
+// without a tolerance the sim would owe — and run — one step fewer than the
+// same time delivered at 60 Hz. A billionth of a step is far below anything a
+// frame clock can resolve, so treating "within it" as whole costs nothing.
+const STEP_TOLERANCE = 1e-9;
+/**
+ * Build a fixed-step schedule over `systems`, run in the order given.
+ *
+ * ```ts
+ * const schedule = createSchedule([intro, stove, mixer, serving], {
+ *   step: 1 / 60,
+ *   maxSteps: 6,
+ * });
+ * // once per rendered frame, with the frame's dt:
+ * schedule.tick(run, frameDt);
+ * ```
+ *
+ * The systems array is copied; later changes to it do not affect the schedule.
+ */
+export function createSchedule(systems, options) {
+    if (!Array.isArray(systems)) {
+        throw new TypeError("createSchedule: systems must be an array of functions.");
+    }
+    const { step, maxSteps } = options;
+    if (!Number.isFinite(step) || step <= 0) {
+        throw new RangeError(`createSchedule: step must be finite and greater than zero; received ${step}.`);
+    }
+    if (!Number.isSafeInteger(maxSteps) || maxSteps < 1) {
+        throw new RangeError(`createSchedule: maxSteps must be a safe integer of at least 1; received ${maxSteps}.`);
+    }
+    if (options.key !== undefined && (typeof options.key !== "string" || options.key === "")) {
+        throw new TypeError("createSchedule: key must be a non-empty string when provided.");
+    }
+    const ordered = Object.freeze([...systems]);
+    for (const system of ordered) {
+        if (typeof system !== "function") {
+            throw new TypeError("createSchedule: every system must be a function.");
+        }
+    }
+    let key;
+    if (options.key === undefined) {
+        // Skip any key a caller has already named, so a default never lands on one.
+        do {
+            key = `schedule:${nextScheduleId++}`;
+        } while (claimedKeys.has(key));
+        generatedKeys.add(key);
+    }
+    else {
+        if (generatedKeys.has(options.key)) {
+            throw new TypeError(`createSchedule: key "${options.key}" is already the generated key of another schedule.`);
+        }
+        key = options.key;
+    }
+    claimedKeys.add(key);
+    const tolerance = step * STEP_TOLERANCE;
+    function read(handle) {
+        const stored = handle.scratch.get(key);
+        if (stored === undefined)
+            return 0;
+        if (typeof stored !== "number" || !Number.isFinite(stored) || stored < 0) {
+            throw new TypeError(`createSchedule: scratch key "${key}" already holds something other than a schedule accumulator.`);
+        }
+        return stored;
+    }
+    function tick(handle, frameDt) {
+        const previous = read(handle);
+        // A pause (and any frame dt that counts as 0) runs nothing, even if a
+        // failed tick left whole steps owed: those wait for a frame that moves time.
+        if (!(Number.isFinite(frameDt) && frameDt > 0))
+            return 0;
+        const sum = previous + frameDt;
+        // Two huge finite frames can sum past the double range; saturate instead of
+        // letting Infinity poison the stored accumulator.
+        let owed = Number.isFinite(sum) ? sum : Number.MAX_VALUE;
+        let ran = 0;
+        try {
+            while (owed + tolerance >= step && ran < maxSteps) {
+                // The clock moves first, so a step it refuses (an exhausted clock) is
+                // never debited. After that the step is spent before any system runs:
+                // if one throws, this step's time is gone with the tick it caused.
+                advanceClock(handle, step);
+                owed = Math.max(0, owed - step);
+                ran++;
+                for (const system of ordered)
+                    system(handle, step);
+            }
+            if (owed + tolerance >= step) {
+                // Capped with whole steps still owed: drop them, keep the fraction.
+                owed %= step;
+                if (owed + tolerance >= step)
+                    owed = 0;
+            }
+        }
+        finally {
+            handle.scratch.set(key, owed);
+        }
+        return ran;
+    }
+    return Object.freeze({
+        step,
+        maxSteps,
+        key,
+        tick,
+        remainder: read,
+    });
+}

package/docs/API.md

@@ -1,8 +1,9 @@
 # API reference
 
-All functions and types are exported from `koota-kit`. The
-module-specific import paths shown below can reduce coupling in larger
-codebases.
+All functions and types are exported from `koota-kit`, except the React
+bindings, which are only available from `koota-kit/react` so the root entry
+never loads React. The module-specific import paths shown below can reduce
+coupling in larger codebases.
 
 ## `world`
 
@@ -173,6 +174,63 @@ const Pose = defineTrait(() => ({ position: { x: 0, y: 0 } }));
 Bare object and array fields are rejected by `SafeSchema` and by the runtime
 guard.
 
+## `schedule`
+
+Import from `koota-kit/schedule` or the root.
+
+```ts
+type System = (handle: WorldHandle, dt: number) => void;
+
+type ScheduleOptions = {
+  step: number;     // seconds per step; finite, > 0
+  maxSteps: number; // safe integer >= 1: most steps one tick may run
+  key?: string;     // scratch key for the accumulator; unique by default
+};
+
+type Schedule = {
+  readonly step: number;
+  readonly maxSteps: number;
+  readonly key: string;
+  tick(handle: WorldHandle, frameDt: number): number;
+  remainder(handle: WorldHandle): number;
+};
+
+function createSchedule(systems: readonly System[], options: ScheduleOptions): Readonly<Schedule>;
+```
+
+`createSchedule` copies `systems` and validates `step`, `maxSteps`, `key` and
+every system before returning; bad configuration throws `TypeError` or
+`RangeError` naming `createSchedule`.
+
+`tick(handle, frameDt)` adds `frameDt` to an accumulator stored in
+`handle.scratch` under `key`, then, while at least one whole `step` is owed and
+fewer than `maxSteps` have run, calls `advanceClock(handle, step)` and then
+every system in order with `dt === step`. It returns the number of steps run.
+Systems read `dt`, never the frame's dt, so the same elapsed time gives the same
+run at any frame rate, provided no single tick owes more than `maxSteps` (the
+excess is dropped, so one long frame and many short ones then differ).
+
+- A `frameDt` that is negative, `NaN` or infinite counts as `0`. `0` is a valid
+  pause: no step runs and the clock does not move, even if a failed tick left
+  whole steps owed; those wait for the next frame that moves time.
+- When `maxSteps` is reached with whole steps still owed, those steps are
+  dropped, not carried. The sub-step fraction is kept, so phase is preserved.
+- Owed time saturates at the largest finite double instead of overflowing.
+- A billionth of a step of tolerance absorbs float drift, so 432 frames of
+  1/144 s run the same 180 steps as 180 frames of 1/60 s.
+- The accumulator lives in `scratch`, so it dies with the world and two
+  handles never share one. A `key` already holding something other than a
+  schedule accumulator throws `TypeError` before the clock moves. Two schedules
+  given the same explicit `key` share one accumulator, but an explicit `key`
+  may not equal another schedule's generated key, and a generated key skips any
+  explicit one.
+- If a system throws, the step it was in is already spent (the clock moved) and
+  the steps not yet started stay owed, so a retry does not replay spent time.
+
+`remainder(handle)` returns the seconds currently owed, in `[0, step)` between
+ticks (`0` on a handle that has not ticked). `remainder / step` is the
+interpolation alpha for a renderer drawing between sim states.
+
 ## `eventLog`
 
 ```ts
@@ -192,3 +250,27 @@ Logs are created once at module scope but store their arrays in each handle's
 scratch map. `drain` truncates the live array in place so an existing internal
 reference is not orphaned. Empty reads do not create a scratch entry. `peek`
 returns a detached array; `size` does not allocate.
+
+## `react`
+
+Import from `koota-kit/react`. Requires `react` (`>=18`), an optional peer
+dependency; no other entry point imports it.
+
+```ts
+type SimWorldProviderProps = {
+  readonly handle: WorldHandle;
+  readonly children?: ReactNode;
+};
+
+const SimWorldProvider: FunctionComponent<SimWorldProviderProps>;
+function useSimWorld(): WorldHandle;
+```
+
+`SimWorldProvider` supplies `handle` to the tree below it and renders
+`koota/react`'s `WorldProvider` for `handle.world`, so `useWorld`, `useTrait`,
+`useQuery` and `useActions` work under it without a second provider.
+`useSimWorld` returns the provided handle, including its `rng`, `seeds`,
+`clock` and `scratch`, and throws an `Error` when no `SimWorldProvider` is above
+it. Passing a different `handle` re-provides every consumer. The provider does
+not create or destroy the handle: pair `createSimWorld` with `destroySimWorld`
+yourself.

package/docs/ARCHITECTURE.md

@@ -11,8 +11,10 @@ traits ───────────────> koota
 seed ─────────────────> (leaf: built-in SHA-256)
 rng ──────────────────> seedrandom + seed
 world ────────────────> koota + rng
+schedule ─────────────> world (advanceClock) + WorldHandle scratch
 eventLog ─────────────> WorldHandle scratch
-index ────────────────> public re-exports only
+react ────────────────> koota/react + react + world (type only)
+index ────────────────> public re-exports only (never react)
 ```
 
 `traits` is a leaf module: it imports Koota but no sibling runtime module. This
@@ -33,9 +35,25 @@ text) is a stable contract: changing it would change every derived world.
 `world` owns allocation, teardown, time, and facade-owned persistence. It does
 not own application entity serialization.
 
+`schedule` turns a frame's dt into whole fixed steps. Its accumulator lives in
+the handle's scratch map, so time owed dies with the run and two schedules or
+two worlds never share it. It imports no renderer: a frame callback calls
+`tick` and that is the whole integration. The step cap drops excess time rather
+than carrying it, so one huge dt cannot cause a catch-up storm.
+
 `eventLog` uses the handle's scratch map so event lifetime matches world
 lifetime. It does not use a process-global queue.
 
+`react` is the only module that imports React, through `koota/react`. It is
+reachable only from the `koota-kit/react` subpath: `index` does not re-export it,
+and `react` is an optional peer dependency, so an application that never imports
+that subpath never needs React installed. It carries the `WorldHandle` through a
+context and mounts Koota's own `WorldProvider` for `handle.world`, which keeps
+one source of truth for the world. It imports `world` for types only and owns no
+lifecycle: creating and destroying the handle stays with the application.
+`pnpm package:check` walks every other built entry's import graph and fails if
+it reaches `react` or `koota/react`.
+
 ## Invariants
 
 1. Seed values on a handle are copied and frozen at creation.
@@ -47,6 +65,11 @@ lifetime. It does not use a process-global queue.
 7. World teardown clears facade-owned scratch state and releases the Koota ID.
 8. A named substream's sequence depends only on its seed and name; creating or
    consuming another substream never shifts it.
+9. Only `koota-kit/react` imports React; every other entry stays React-free.
+10. A schedule's systems only ever see `dt === step`; the same elapsed time
+    delivered at any frame rate runs the same steps in the same order, as long
+    as no single tick owes more than `maxSteps` (beyond that, the excess is
+    dropped by design, so a one-second frame and sixty 1/60 s frames differ).
 
 ## Performance choices
 
@@ -61,8 +84,10 @@ lifetime. It does not use a process-global queue.
 ## Intentional limits
 
 - No entity/trait serializer: applications need versioned domain schemas.
-- No scheduler or system runner: Koota's queries/actions remain the execution
-  model.
+- No system graph: `createSchedule` runs an ordered list once per fixed step,
+  and nothing more. There is no dependency resolution, parallelism, or
+  per-system rate; a system that wants a slower cadence counts steps itself.
+  Koota's queries/actions remain the execution model inside each system.
 - No implicit derived keys: `deriveSeed` hashes only the parts the application
   passes, so the application still owns stable domain keys.
 - No multi-consumer queue semantics: publish separate logs when two systems

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koota-kit",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Deterministic Koota simulation conventions: world lifecycle, dual RNG streams, safe object traits, and world-scoped event logs.",
   "type": "module",
   "license": "MIT",
@@ -63,6 +63,16 @@
         "default": "./dist/cjs/traits/index.cjs"
       }
     },
+    "./schedule": {
+      "import": {
+        "types": "./dist/esm/schedule.d.ts",
+        "default": "./dist/esm/schedule.js"
+      },
+      "require": {
+        "types": "./dist/cjs/schedule.d.cts",
+        "default": "./dist/cjs/schedule.cjs"
+      }
+    },
     "./eventLog": {
       "import": {
         "types": "./dist/esm/eventLog.d.ts",
@@ -73,6 +83,16 @@
         "default": "./dist/cjs/eventLog.cjs"
       }
     },
+    "./react": {
+      "import": {
+        "types": "./dist/esm/react.d.ts",
+        "default": "./dist/esm/react.js"
+      },
+      "require": {
+        "types": "./dist/cjs/react.d.cts",
+        "default": "./dist/cjs/react.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -109,18 +129,33 @@
     "seedrandom": "^3.0.5"
   },
   "peerDependencies": {
-    "koota": "^0.6.6"
+    "@types/react": ">=18.0.0",
+    "koota": "^0.6.6",
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@biomejs/biome": "^2.5.5",
     "@commitlint/cli": "^21.2.2",
     "@commitlint/config-conventional": "^21.2.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@vitest/coverage-v8": "^3.2.7",
+    "jsdom": "^30.1.2",
     "koota": "^0.6.6",
     "lint-staged": "^17.3.0",
     "markdownlint-cli2": "^0.23.2",
     "publint": "^0.3.24",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "simple-git-hooks": "^2.13.1",
     "typescript": "^5.9.2",
     "vitest": "^3.2.4"
@@ -163,9 +198,15 @@
       "traits": [
         "./dist/esm/traits/index.d.ts"
       ],
+      "schedule": [
+        "./dist/esm/schedule.d.ts"
+      ],
       "eventLog": [
         "./dist/esm/eventLog.d.ts"
       ],
+      "react": [
+        "./dist/esm/react.d.ts"
+      ],
       "*": [
         "./dist/esm/index.d.ts"
       ]