koota-kit 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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)
 
 

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/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/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/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`
 
@@ -192,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.4.0",
+  "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"
       ]