@jgengine/react 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All eight `@jgengine/*` packages are versioned in lockstep, so this one file
+covers every release. Format follows [Keep a Changelog](https://keepachangelog.com);
+each release **leads with a Migrate block** — the concrete steps to move a game
+from the previous version onto the new APIs — because the point of a bump is to
+let consumers pick up the better stuff, not just to list what moved.
+
+Agents building on the published SDK can also read this programmatically:
+`import { VERSION, CHANGELOG } from "@jgengine/core/meta/changelog"` gives the
+same data as typed values, so an updater can diff its installed version against
+the latest and surface the migration steps.
+
+## Unreleased
+
+_Nothing yet._
+
+## 0.5.0
+
+An additive release: **every 0.4.0 API is unchanged**, so upgrading is only a
+version bump. New pure primitives across progression, inventory slots, world
+geometry, and React store bindings.
+
+### Migrate
+
+- Bump every `@jgengine/*` dependency to `^0.5.0` (the eight packages version in lockstep).
+- No code change is required — 0.5.0 adds surface, it doesn't move or remove any.
+- Optional: replace a game's hand-rolled `progression/curves.ts` with the new `leveling(...)` track. `leveling({ xpForLevel: { kind: "power", base, exponent, round: "floor" }, maxLevel })` returns `xpForLevel`, `resolve`, and `grantXp(ctx.scene.entity.stats, userId, amount, onLevelUp?)` — a drop-in for the old `xpRequiredForLevel` / `resolveLevelProgress` / `grantXp` exports. `ctx.scene.entity.stats` satisfies the primitive's `LevelingStatAccess` structurally, so no adapter is needed.
+
+### Added
+
+- `@jgengine/core/game/progression` — genre-agnostic progression primitive. `curve(spec)` / `evalCurve(spec, x)` evaluate declarative scalar curves (`const`, `linear`, `power`, `geometric`, `steps`, `piecewise`, each with optional `round`/`min`/`max`) for speed-by-level, difficulty-by-wave, loot drop-rate ramps, and similar scaling. `leveling(config)` builds the stateful XP→level track (threshold accumulation, multi-level grants, cap handling, `stat.levelUp` emit) on top of an `xpForLevel` curve.
+- `@jgengine/core/inventory/slotModel` — pure slot-grid primitives (`createSlots`, `placeAt`, `removeAt`, `moveSlot`).
+- `@jgengine/core/world/geometry`, `/world/interiors`, `/world/placement` — pure world primitives: grid snapping, footprint AABBs and overlap, interior/exterior spaces, and placement validation.
+- `@jgengine/react/engineStore` — raw-store React bindings (`useEngineState`, `useEngineStore`, `useEngineEvent`).
+- Pure/functional tiers for the `trade`, `unlocks`, `quest`, and `feed` verbs in `@jgengine/core/game`.
+
+## 0.4.0
+
+Baseline release: the eight `@jgengine/*` packages (core, ws, sql, react,
+convex, node, shell, assets) as the first tracked version. No migration —
+this is the floor changelog entries are measured against.

package/dist/engineStore.d.ts

@@ -0,0 +1,10 @@
+export interface ReadableEngineStore<TState> {
+    getState(): TState;
+    subscribe(listener: (state: TState) => void): () => void;
+}
+export interface EventfulEngineStore<TEventMap extends object> {
+    on<K extends keyof TEventMap>(eventName: K, listener: (payload: TEventMap[K]) => void): () => void;
+}
+export declare function useEngineState<TState>(store: ReadableEngineStore<TState>): TState;
+export declare function useEngineStore<TState, TSelected>(store: ReadableEngineStore<TState>, selector: (state: TState) => TSelected): TSelected;
+export declare function useEngineEvent<TEventMap extends object, K extends keyof TEventMap>(store: EventfulEngineStore<TEventMap>, eventName: K, handler: (payload: TEventMap[K]) => void): void;

package/dist/engineStore.js

@@ -0,0 +1,14 @@
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+export function useEngineState(store) {
+    const subscribe = useCallback((onChange) => store.subscribe(() => onChange()), [store]);
+    const getSnapshot = useCallback(() => store.getState(), [store]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+export function useEngineStore(store, selector) {
+    return selector(useEngineState(store));
+}
+export function useEngineEvent(store, eventName, handler) {
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    useEffect(() => store.on(eventName, (payload) => handlerRef.current(payload)), [store, eventName]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/react",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "React UI layer for JGengine: GameProvider, hooks, and headless primitives over @jgengine/core.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -10,7 +10,10 @@
     "url": "git+https://github.com/Noisemaker111/jgengine.git",
     "directory": "packages/react"
   },
-  "files": ["dist"],
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
   "exports": {
     "./*": {
       "types": "./dist/*.d.ts",
@@ -22,7 +25,7 @@
     "check-types": "tsgo --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@jgengine/core": "^0.4.0"
+    "@jgengine/core": "^0.5.0"
   },
   "peerDependencies": {
     "react": "^19.0.0"