@jgengine/react 0.3.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/components.d.ts

@@ -1,6 +1,8 @@
-import type { ReactNode } from "react";
+import { type ReactNode } from "react";
 import type { InventorySlot } from "@jgengine/core/inventory/inventoryModel";
 import type { ProximityPrompt as ProximityPromptDef } from "@jgengine/core/interaction/proximityPrompt";
+import type { FeedEntry } from "@jgengine/core/game/feed";
+import type { StatLevelUpEvent } from "@jgengine/core/game/events";
 export declare function SlotGrid({ inventoryId, className, renderSlot, }: {
     inventoryId: string;
     className?: string;
@@ -53,3 +55,22 @@ export declare function DialogueBox({ dialogue, onChoice, className, }: {
     onChoice?: (choice: DialogueChoice) => void;
     className?: string;
 }): import("react").JSX.Element;
+export declare function ToastStack({ action, limit, className, renderToast, }: {
+    action: string;
+    limit?: number;
+    className?: string;
+    renderToast?: (entry: FeedEntry, index: number) => ReactNode;
+}): import("react").JSX.Element | null;
+export declare function DeathScreen({ statId, open, className, children, }: {
+    statId?: string;
+    open?: boolean;
+    className?: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function LevelUpFlash({ stat, durationMs, className, children, renderFlash, }: {
+    stat?: string;
+    durationMs?: number;
+    className?: string;
+    children?: ReactNode;
+    renderFlash?: (event: StatLevelUpEvent) => ReactNode;
+}): import("react").JSX.Element | null;

package/dist/components.js

@@ -1,5 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCurrency, useEntityStat, useInventory } from "./hooks.js";
+import { useEffect, useRef, useState } from "react";
+import { useGameContext } from "./provider.js";
+import { useCurrency, useEntityStat, useFeed, useInventory, useLocalPlayerDead } from "./hooks.js";
 export function SlotGrid({ inventoryId, className, renderSlot, }) {
     const slots = useInventory(inventoryId);
     return (_jsx("div", { className: className, "data-inventory": inventoryId, children: slots.map((slot, index) => (_jsx("div", { "data-slot": index, children: renderSlot !== undefined
@@ -41,3 +43,44 @@ export function KeybindRow({ action, keys, className, }) {
 export function DialogueBox({ dialogue, onChoice, className, }) {
     return (_jsx("div", { className: className, "data-dialogue": dialogue.id, children: dialogue.lines.map((line, index) => "choices" in line ? (_jsx("div", { "data-choices": true, children: line.choices.map((choice) => (_jsx("button", { type: "button", onClick: () => onChoice?.(choice), children: choice.label }, choice.label))) }, index)) : (_jsxs("p", { children: [_jsx("span", { "data-speaker": true, children: line.speaker }), _jsx("span", { children: line.text })] }, index))) }));
 }
+function defaultToast(entry) {
+    const data = entry.data;
+    if (data?.drops !== undefined) {
+        return data.drops.map((drop) => `${drop.item ?? drop.currency ?? "item"} ×${drop.count}`).join("  ");
+    }
+    return typeof entry.data === "string" ? entry.data : JSON.stringify(entry.data);
+}
+export function ToastStack({ action, limit = 4, className, renderToast, }) {
+    const entries = useFeed({ action, limit });
+    if (entries.length === 0)
+        return null;
+    const newestFirst = [...entries].reverse();
+    return (_jsx("div", { className: className, "data-toast-stack": action, children: newestFirst.map((entry, index) => (_jsx("div", { "data-toast": true, children: renderToast !== undefined ? renderToast(entry, index) : defaultToast(entry) }, `${entry.at}-${index}`))) }));
+}
+export function DeathScreen({ statId = "health", open, className, children, }) {
+    const dead = useLocalPlayerDead(statId);
+    return (_jsx(Screen, { id: "death", open: open ?? dead, className: className, children: children }));
+}
+export function LevelUpFlash({ stat, durationMs = 1600, className, children, renderFlash, }) {
+    const ctx = useGameContext();
+    const [flash, setFlash] = useState(null);
+    const timerRef = useRef(null);
+    useEffect(() => {
+        const unsubscribe = ctx.game.events.on("stat.levelUp", (event) => {
+            if (stat !== undefined && event.stat !== stat)
+                return;
+            setFlash(event);
+            if (timerRef.current !== null)
+                clearTimeout(timerRef.current);
+            timerRef.current = setTimeout(() => setFlash(null), durationMs);
+        });
+        return () => {
+            unsubscribe();
+            if (timerRef.current !== null)
+                clearTimeout(timerRef.current);
+        };
+    }, [ctx, stat, durationMs]);
+    if (flash === null)
+        return null;
+    return (_jsx("div", { className: className, "data-levelup": flash.level, children: renderFlash !== undefined ? renderFlash(flash) : children ?? `Level ${flash.level}` }));
+}

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/dist/hooks.d.ts

@@ -39,5 +39,6 @@ export declare function useLeaderboard(stat: string, options: {
     userId: string;
     value: number;
 }[];
+export declare function useLocalPlayerDead(healthStatId?: string): boolean;
 export declare function localPlayerEntity(ctx: GameContext): SceneEntity | null;
 export declare function useActivePrompt<T extends PositionedPrompt>(prompts?: readonly T[]): T | null;

package/dist/hooks.js

@@ -50,6 +50,15 @@ export function usePresence(userId) {
 export function useLeaderboard(stat, options) {
     return useGameStore((ctx) => ctx.game.leaderboard.getTop(stat, options));
 }
+export function useLocalPlayerDead(healthStatId = "health") {
+    return useGameStore((ctx) => {
+        const player = localPlayerEntity(ctx);
+        if (player === null)
+            return false;
+        const health = ctx.scene.entity.stats.get(player.id, healthStatId);
+        return health !== null && health.current <= health.min;
+    });
+}
 export function localPlayerEntity(ctx) {
     return (ctx.scene.entity.get(ctx.player.userId) ??
         ctx.scene.entity.list().find((entity) => entity.role === "player") ??

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/react",
-  "version": "0.3.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",
@@ -18,11 +21,11 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && bun ../../scripts/fix-extensions.ts dist",
-    "check-types": "tsc --noEmit -p tsconfig.json"
+    "build": "tsgo -p tsconfig.build.json && bun ../../scripts/fix-extensions.ts dist",
+    "check-types": "tsgo --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@jgengine/core": "^0.3.0"
+    "@jgengine/core": "^0.5.0"
   },
   "peerDependencies": {
     "react": "^19.0.0"