koota-kit 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* **rng:** pick and shuffle over a stream ([167eb1c](https://github.com/jbcom/koota-kit/commit/167eb1c75fdb7aa2b78f9d9d4e2533c81e0b5230))
+
 ## [0.3.1](https://github.com/jbcom/koota-kit/compare/v0.3.0...v0.3.1) (2026-10-07)
 
 

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.
@@ -154,9 +156,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 |
 | --- | --- |
@@ -165,6 +206,7 @@ The root package exports the full API. Focused entry points are also available:
 | `koota-kit/seed` | Seed derivation and 128-bit master seeds |
 | `koota-kit/traits` | Safe trait declaration |
 | `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

package/dist/cjs/index.cjs

@@ -12,7 +12,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.restoreSubstreams = exports.restoreStream = exports.restoreLayers = 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.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; } });
@@ -30,9 +30,11 @@ Object.defineProperty(exports, "getSubstream", { enumerable: true, get: function
 Object.defineProperty(exports, "nextFloat", { enumerable: true, get: function () { return rng_js_1.nextFloat; } });
 Object.defineProperty(exports, "nextInt", { enumerable: true, get: function () { return rng_js_1.nextInt; } });
 Object.defineProperty(exports, "nextU32", { enumerable: true, get: function () { return rng_js_1.nextU32; } });
+Object.defineProperty(exports, "pick", { enumerable: true, get: function () { return rng_js_1.pick; } });
 Object.defineProperty(exports, "restoreLayers", { enumerable: true, get: function () { return rng_js_1.restoreLayers; } });
 Object.defineProperty(exports, "restoreStream", { enumerable: true, get: function () { return rng_js_1.restoreStream; } });
 Object.defineProperty(exports, "restoreSubstreams", { enumerable: true, get: function () { return rng_js_1.restoreSubstreams; } });
+Object.defineProperty(exports, "shuffle", { enumerable: true, get: function () { return rng_js_1.shuffle; } });
 Object.defineProperty(exports, "snapshotLayers", { enumerable: true, get: function () { return rng_js_1.snapshotLayers; } });
 Object.defineProperty(exports, "snapshotStream", { enumerable: true, get: function () { return rng_js_1.snapshotStream; } });
 Object.defineProperty(exports, "snapshotSubstreams", { enumerable: true, get: function () { return rng_js_1.snapshotSubstreams; } });

package/dist/cjs/index.d.cts

@@ -1,6 +1,6 @@
 export { advanceClock, createActions, createSimWorld, destroySimWorld, relation, restoreWorldHeader, snapshotWorld, trait, } from "./world.cjs";
 export type { Entity, World, WorldHandle, WorldSnapshot } from "./world.cjs";
-export { chance, createRng, createSubstreams, getSubstream, nextFloat, nextInt, nextU32, restoreLayers, restoreStream, restoreSubstreams, snapshotLayers, snapshotStream, snapshotSubstreams, substream, } from "./rng.cjs";
+export { chance, createRng, createSubstreams, getSubstream, nextFloat, nextInt, nextU32, pick, restoreLayers, restoreStream, restoreSubstreams, shuffle, snapshotLayers, snapshotStream, snapshotSubstreams, substream, } from "./rng.cjs";
 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";

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,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,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":"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"}

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/rng.cjs

@@ -28,6 +28,8 @@ exports.nextU32 = nextU32;
 exports.nextFloat = nextFloat;
 exports.nextInt = nextInt;
 exports.chance = chance;
+exports.pick = pick;
+exports.shuffle = shuffle;
 exports.snapshotStream = snapshotStream;
 exports.snapshotLayers = snapshotLayers;
 exports.restoreStream = restoreStream;
@@ -118,6 +120,33 @@ function chance(stream, p) {
     }
     return nextFloat(stream) < p;
 }
+/**
+ * Pick one element of `items` uniformly. Valid calls consume exactly one
+ * `nextInt` draw; an empty array is rejected without consuming the stream,
+ * so a caller can never silently skip a draw it meant to make.
+ */
+function pick(stream, items) {
+    if (items.length === 0) {
+        throw new RangeError("pick: items must not be empty.");
+    }
+    return items[nextInt(stream, 0, items.length)];
+}
+/**
+ * Return a uniformly shuffled copy of `items` (Fisher–Yates, from the last
+ * index down). The input is never mutated. Valid calls consume exactly
+ * `items.length - 1` draws (none for zero or one element), so the draw count
+ * depends only on the length — replay stays aligned whatever the contents.
+ */
+function shuffle(stream, items) {
+    const out = [...items];
+    for (let i = out.length - 1; i > 0; i--) {
+        const j = nextInt(stream, 0, i + 1);
+        const swap = out[i];
+        out[i] = out[j];
+        out[j] = swap;
+    }
+    return out;
+}
 /**
  * Capture `stream`'s internal seedrandom state as a plain, JSON-serializable
  * object (deep-cloned, so later draws on `stream` cannot mutate the

package/dist/cjs/rng.d.cts

@@ -50,6 +50,19 @@ export declare function nextInt(stream: RngStream, minInclusive: number, maxExcl
  * deterministic across codepaths that must replay identically.
  */
 export declare function chance(stream: RngStream, p: number): boolean;
+/**
+ * Pick one element of `items` uniformly. Valid calls consume exactly one
+ * `nextInt` draw; an empty array is rejected without consuming the stream,
+ * so a caller can never silently skip a draw it meant to make.
+ */
+export declare function pick<T>(stream: RngStream, items: readonly T[]): T;
+/**
+ * Return a uniformly shuffled copy of `items` (Fisher–Yates, from the last
+ * index down). The input is never mutated. Valid calls consume exactly
+ * `items.length - 1` draws (none for zero or one element), so the draw count
+ * depends only on the length — replay stays aligned whatever the contents.
+ */
+export declare function shuffle<T>(stream: RngStream, items: readonly T[]): T[];
 export type RngStreamSnapshot = {
     state: State;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"rng.d.ts","sourceRoot":"","sources":["../../src/rng.ts"],"names":[],"mappings":"AAqBA,OAAO,UAAU,MAAM,YAAY,CAAC;AAGpC,KAAK,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;AACnC,KAAK,QAAQ,GAAG,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;AAE/C,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,QAAQ,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,SAAS,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CAClC,CAAC;AAgBF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAUpD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAc7F;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAK5D;AAED,MAAM,MAAM,iBAAiB,GAAG;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AACjD,MAAM,MAAM,iBAAiB,GAAG;IAAE,GAAG,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAEtF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,iBAAiB,CAGnE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,SAAS,GAAG,iBAAiB,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,CAqBhE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,CAKhE;AAUD,MAAM,MAAM,UAAU,GAAG;IACvB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC5C,CAAC;AAcF;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAGxE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAGlE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAO5E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,GAAG,kBAAkB,CAW7E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,UAAU,CAiB1E"}
+{"version":3,"file":"rng.d.ts","sourceRoot":"","sources":["../../src/rng.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.d.ts

@@ -1,6 +1,6 @@
 export { advanceClock, createActions, createSimWorld, destroySimWorld, relation, restoreWorldHeader, snapshotWorld, trait, } from "./world.js";
 export type { Entity, World, WorldHandle, WorldSnapshot } from "./world.js";
-export { chance, createRng, createSubstreams, getSubstream, nextFloat, nextInt, nextU32, restoreLayers, restoreStream, restoreSubstreams, snapshotLayers, snapshotStream, snapshotSubstreams, substream, } from "./rng.js";
+export { chance, createRng, createSubstreams, getSubstream, nextFloat, nextInt, nextU32, pick, restoreLayers, restoreStream, restoreSubstreams, shuffle, snapshotLayers, snapshotStream, snapshotSubstreams, substream, } from "./rng.js";
 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";

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,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,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":"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"}

package/dist/esm/index.js

@@ -11,7 +11,7 @@
 //   ./eventLog — scratch-backed publish/drain event logs with a peek seam for
 //                observers (harnesses, tests, HUDs)
 export { advanceClock, createActions, createSimWorld, destroySimWorld, relation, restoreWorldHeader, snapshotWorld, trait, } from "./world.js";
-export { chance, createRng, createSubstreams, getSubstream, nextFloat, nextInt, nextU32, restoreLayers, restoreStream, restoreSubstreams, snapshotLayers, snapshotStream, snapshotSubstreams, substream, } from "./rng.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 { 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/rng.d.ts

@@ -50,6 +50,19 @@ export declare function nextInt(stream: RngStream, minInclusive: number, maxExcl
  * deterministic across codepaths that must replay identically.
  */
 export declare function chance(stream: RngStream, p: number): boolean;
+/**
+ * Pick one element of `items` uniformly. Valid calls consume exactly one
+ * `nextInt` draw; an empty array is rejected without consuming the stream,
+ * so a caller can never silently skip a draw it meant to make.
+ */
+export declare function pick<T>(stream: RngStream, items: readonly T[]): T;
+/**
+ * Return a uniformly shuffled copy of `items` (Fisher–Yates, from the last
+ * index down). The input is never mutated. Valid calls consume exactly
+ * `items.length - 1` draws (none for zero or one element), so the draw count
+ * depends only on the length — replay stays aligned whatever the contents.
+ */
+export declare function shuffle<T>(stream: RngStream, items: readonly T[]): T[];
 export type RngStreamSnapshot = {
     state: State;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"rng.d.ts","sourceRoot":"","sources":["../../src/rng.ts"],"names":[],"mappings":"AAqBA,OAAO,UAAU,MAAM,YAAY,CAAC;AAGpC,KAAK,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;AACnC,KAAK,QAAQ,GAAG,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;AAE/C,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,QAAQ,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,SAAS,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CAClC,CAAC;AAgBF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAUpD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAc7F;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAK5D;AAED,MAAM,MAAM,iBAAiB,GAAG;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AACjD,MAAM,MAAM,iBAAiB,GAAG;IAAE,GAAG,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAEtF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,iBAAiB,CAGnE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,SAAS,GAAG,iBAAiB,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,CAqBhE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,CAKhE;AAUD,MAAM,MAAM,UAAU,GAAG;IACvB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC5C,CAAC;AAcF;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAGxE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAGlE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAO5E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,GAAG,kBAAkB,CAW7E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,UAAU,CAiB1E"}
+{"version":3,"file":"rng.d.ts","sourceRoot":"","sources":["../../src/rng.ts"],"names":[],"mappings":"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"}

package/dist/esm/rng.js

@@ -99,6 +99,33 @@ export function chance(stream, p) {
     }
     return nextFloat(stream) < p;
 }
+/**
+ * Pick one element of `items` uniformly. Valid calls consume exactly one
+ * `nextInt` draw; an empty array is rejected without consuming the stream,
+ * so a caller can never silently skip a draw it meant to make.
+ */
+export function pick(stream, items) {
+    if (items.length === 0) {
+        throw new RangeError("pick: items must not be empty.");
+    }
+    return items[nextInt(stream, 0, items.length)];
+}
+/**
+ * Return a uniformly shuffled copy of `items` (Fisher–Yates, from the last
+ * index down). The input is never mutated. Valid calls consume exactly
+ * `items.length - 1` draws (none for zero or one element), so the draw count
+ * depends only on the length — replay stays aligned whatever the contents.
+ */
+export function shuffle(stream, items) {
+    const out = [...items];
+    for (let i = out.length - 1; i > 0; i--) {
+        const j = nextInt(stream, 0, i + 1);
+        const swap = out[i];
+        out[i] = out[j];
+        out[j] = swap;
+    }
+    return out;
+}
 /**
  * Capture `stream`'s internal seedrandom state as a plain, JSON-serializable
  * object (deep-cloned, so later draws on `stream` cannot mutate the

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`
 
@@ -68,6 +69,8 @@ function nextU32(stream: RngStream): number;
 function nextFloat(stream: RngStream): number;
 function nextInt(stream: RngStream, minInclusive: number, maxExclusive: number): number;
 function chance(stream: RngStream, probability: number): boolean;
+function pick<T>(stream: RngStream, items: readonly T[]): T;
+function shuffle<T>(stream: RngStream, items: readonly T[]): T[];
 function snapshotStream(stream: RngStream): RngStreamSnapshot;
 function restoreStream(snapshot: RngStreamSnapshot): RngStream;
 function snapshotLayers(layers: RngLayers): RngLayersSnapshot;
@@ -79,6 +82,11 @@ function restoreLayers(snapshot: RngLayersSnapshot): RngLayers;
 - `nextInt` uses half-open bounds and exactly one float draw after validation.
 - `chance` consumes one draw for every valid probability, including `0` and
   `1`, keeping later draw positions predictable.
+- `pick` returns one element uniformly with exactly one `nextInt` draw and
+  rejects an empty array without drawing.
+- `shuffle` returns a Fisher–Yates shuffled copy (the input is never mutated)
+  and consumes exactly `length - 1` draws, so the draw count depends only on
+  the length, never on the contents.
 - Restore functions reject malformed ARC4 state and clone accepted state so a
   snapshot can seed multiple independent replays.
 
@@ -185,3 +193,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

@@ -12,7 +12,8 @@ seed ─────────────────> (leaf: built-in SHA-25
 rng ──────────────────> seedrandom + seed
 world ────────────────> koota + rng
 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
@@ -36,6 +37,16 @@ not own application entity serialization.
 `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 +58,7 @@ 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.
 
 ## Performance choices
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koota-kit",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Deterministic Koota simulation conventions: world lifecycle, dual RNG streams, safe object traits, and world-scoped event logs.",
   "type": "module",
   "license": "MIT",
@@ -73,6 +73,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 +119,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"
@@ -166,6 +191,9 @@
       "eventLog": [
         "./dist/esm/eventLog.d.ts"
       ],
+      "react": [
+        "./dist/esm/react.d.ts"
+      ],
       "*": [
         "./dist/esm/index.d.ts"
       ]