@jgengine/react 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -11,6 +11,69 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
+## Unreleased
+
+## 0.9.0
+
+### Added
+
+- Mobile HUD fit — design-resolution UI scaling now applies to every game by default: `HudCanvas` measures the live viewport and scales the whole HUD from `PlayableGame.hudFit.designSize` (default 1600×900, clamps `minScale`/`maxScale` 0.4–1) so desktop-authored layouts shrink to fit a phone instead of overflowing it; `hudFit.mobile` overrides tune the phone fit separately. Pure math lives in `@jgengine/core/ui/hudScale` (`hudScaleForViewport`, `resolveHudFit`, `rectOverflow`, `overflowingPanels`); the shell mounts `@jgengine/react`'s `HudViewportProvider` around `GameUI` so games need no wiring.
+- Graphics → UI scale — a player-facing `graphics.uiScale` slider (0.5–1.5, default 1) multiplies the computed HUD scale on every platform; the same resolution system drives desktop preference and mobile shrink.
+- HUD overflow gate — `HudCanvas` measures every `HudPanel` against the viewport at runtime and reports offenders on a `data-hud-overflow` attribute (plus a console warning); `bun run shoot <game> --device mobile|both` now exits non-zero naming the panels that escape the viewport.
+- Automatic visibility & streaming defaults — an engine-level `VisibilitySystem` (exported from `@jgengine/core`) gives every scene renderer-agnostic culling and asset-streaming policy with no per-object wiring: distance culling, preload margins, hysteresis, delayed unloading, multi-camera awareness (including cameras excluded from streaming), and per-object overrides (always-visible, never-unload, disabled culling/streaming, custom render distance and preload margin).
+- Self-hosted asset mirror — `DEFAULT_RELEASE_BASE` now points at this repo's rolling `packs` release instead of the upstream host; a catalog-driven `mirror-assets` workflow (weekly cron + manual dispatch) keeps the mirror in sync with the asset catalog.
+
+### Changed
+
+- Mobile HUD fit is on by default — design-resolution HUD scaling now applies to every game with no config change (previously opt-in via `platforms: ["web", "mobile"]`). A desktop-only game keeps the legacy fixed 0.85 compact zoom by declaring `platforms: ["web"]` (without `"mobile"`).
+
+## 0.8.0
+
+Transport-agnostic multiplayer (socket.io, WebRTC p2p, LAN/Fly adapters) plus grid/voxel
+and puzzle primitives, HUD-only presentation, cumulative leveling, and a round of
+controller/camera/sensor additions. **Breaking:** the `gameui` component kit moved out of
+`@jgengine/react` onto the shadcn registry.
+
+### Migrate
+
+- Bump every `@jgengine/*` dependency to `^0.8.0` (the eight packages version in lockstep).
+- Additive only, except for `gameui` — every other 0.7.0 API is unchanged; opt into any of the below by importing it directly.
+- **Breaking:** replace any `@jgengine/react/gameui` import with the equivalent registry component (`npx shadcn@latest add https://jgengine.com/r/<name>.json`), and swap `GameUiThemeProvider` for `--jg-*` CSS variables on a wrapper element. `GameIcon` and friends moved to `@jgengine/react/gameIcons`.
+- `leveling({ thresholdMode: 'cumulative' })` is opt-in; the default `perLevel` behavior is unchanged.
+- `defineGame.physics.gravity`/`jumpVelocity` are now read by the built-in kinematics controller every frame — if a game already set them expecting a no-op, jump/fall now actually reflects them; omit both to keep the previous defaults.
+
+### Added
+
+- Cumulative leveling — `leveling({ thresholdMode: 'cumulative' })` tracks xp as a lifetime total that resolves upward across levels and clamps at the max-level threshold once capped (#12).
+- Direction-aware pool depletion — `EffectSystem.canReceive(instanceId, effect, magnitude?)` takes an optional signed magnitude; negative checks the opposite direction and returns `pools-depleted` only when every stat in the receive order is already at max, so heals reach fully-depleted targets (#168).
+- Puzzle primitives — `puzzle/cellGrid` (uniform-cell boards: line-clear, match-3 cascade, run detection) and `puzzle/fallingPiece` (rotation-state shapes, ghost drop, lock delay, classic gravity/level/score curves) for Tetris/match-3 games (#166).
+- Voxel field — `world/voxelField` (`createVoxelField`, chunked block lattice, neighbors/exposedFaces, 3D DDA raycast, dirty-tracked `chunkVersion`) for voxel games and instanced renderers; assert on `field.summary()` the way environment worlds assert on `summarizeEnvironment` (#166).
+- `defineGame` games may omit `assets` (an empty catalog is injected); `PlayableGame.presentation: 'hud'` mounts no 3D canvas/camera/pointer for board/card/menu games; an `environment()` world auto-renders as the shell's backdrop when `PlayableGame.environment` is unset (#166).
+- Declared-action intent board — `turn/intent` `createIntentBoard` for one-turn-ahead intents (Slay-the-Spire style): declare/peek/all/consume/clear (#168).
+- `turnLoop` lifecycle hooks — `config.onTurnStart`/`onTurnEnd` fire on every `advanceTurn()`; `ctx.game.turn.loop(id, config)` lazily creates/returns a notify-wrapped `TurnLoop` so every mutation (`advanceTurn`/`advancePhase`/`advanceRound`/`spend`/`gain`/`refill`/`setOrder`/...) auto-bumps `ctx.version()` with no manual wiring (#163/#168).
+- `ctx.game.store` — a reactive per-game keyed store (`set`/`delete`/`get`/`has`/`subscribe`/`mapSnapshot`/`arraySnapshot`) plus `@jgengine/react`'s `useGameStore` selector hook, replacing hand-rolled module-level stores for ad-hoc reactive game state; `ctx.game.cards.pile(id, config?)` lazily creates/returns a notify-wrapped `CardPile` the same way; `createCardPile` gained an `onChange` hook for headless use; `CommandDefinition.apply` may return void for side-effect-only commands (#163).
+- Camera — `sideScroll` rig (fixed lateral follow for 2.5D platformers/beat-'em-ups), a `none` rig (no camera mounted; pairs with `PlayableGame.presentation: 'hud'`), `rts.pan: false` (static backdrop camera: no pan/edge-scroll/rotate/zoom, still re-centers on the follow target), and the `observer` rig now defaults to the local player when `bind` is unset (#167).
+- Sensors + session — `sensor/concealment` (`colorDistance`/`concealmentScore`/`createConcealmentSensor`), `sensor/freezeMonitor` (`createFreezeMonitor`), `session/roles` (`assignRoles`); `createRoundState`'s `RoundConfig.teams` accepts per-team roles and an optional `winCondition` that `evaluate()` checks each tick, and takes an optional `phaseOrder` for arbitrary named phase cycles (`concludeRound`/`evaluate` settle only while the current phase is neither the first nor the last entry) (#151).
+- Appearance replication — presence rows carry an optional per-slot appearance channel (cosmetic ids, hex tints, model keys) alongside pose, riding the existing pose message with no protocol bump; wire `ctx.player.cosmetics.get(userId)` into the outgoing pose (#151).
+- `ctx.input` — a per-frame held-action snapshot (`publish(held)`/`isDown(action)`/`held()`) without bumping `ctx.version()`; action bindings gained `repeatMs` (repeat-fire while held); every command resolved from a bound action now carries `aim`; `pointer.secondaryCommand` runs a command on right-click off the same raycast as move/ping (#164).
+- Object spatial queries + entity patching — `ctx.scene.object.at`/`inBox`/`raycast`/`raycastAll` over unit-box objects; `ctx.scene.entity.update(id, patch)` for name/position/rotation/role/movement/behaviors/meta; per-instance `renderObject`/`objectStyles` overrides; `pointerService.worldHitCenter()` + pointer-lock center-ray aiming (#165).
+- Controller movement config — `PlayerMovementConfig` (`mode`: free/axis/grid, `axis`, `cellSize`, `collideObjects`, `beforeCommit` pre-commit hook) for the shell-driven walk controller; `defineGame.physics.gravity`/`jumpVelocity` are honored by the built-in walk controller (distinct from the standalone `physics/physicsWorld` rigid-body sim); `ctx.player.motion.impulse`/`setVerticalVelocity`/`setY`/`takePending` (`MotionIntents`); `entity.spawnPoseOf`/`resetToSpawn`/`resetAllToSpawn` (#162).
+- Model material/animation + paint — `ModelConfig.tint`/`metalness`/`roughness`/`animation` (GLTF clip playback, paused pose holds); `PointerHit.uv` + `pointerService.sampleSurface()` for material-aware picking; `ctx.scene.entity.paint` runtime paint layer, auto-rendered via a per-instance canvas texture with no per-game wiring; remote-player appearance tint recolors the shell's default capsule (#151).
+- **Transport pipe seam** (`@jgengine/ws/pipe`) — `createWsBackend` runs over any bidirectional string channel, not just a raw `WebSocket`: `TransportPipe`/`TransportPipeHandlers`/`TransportPipeFactory`, with `webSocketPipe(url, webSocketFactory?)` as the default. `createWsBackend({ userId, url?, pipe? })` — `url` stays the common case, `pipe` opens the seam to socket.io, WebRTC, and in-process loopback below.
+- **Browser-safe authoritative host** — `createGameHost` and `memoryPersistence` moved from `@jgengine/node` to `@jgengine/ws/host` (zero Node dependencies; `@jgengine/node` re-exports both unchanged from `@jgengine/node/host` / `@jgengine/node/persistence`, so existing imports keep working). `@jgengine/ws/hostRouter`'s `createHostRouter({ host, authenticate?, poseRules?, positionHistoryMs?, chatRateLimit?, chatHistoryLimit?, chatMaxBodyLength?, now? })` extracts the ws wire-protocol session logic out of `createGameWsServer` into a transport-agnostic `HostRouter` (`connect(transport) → { handleRaw, close }`, `rewind`, `close`); `@jgengine/node`'s `createGameWsServer` is now a thin binding of this router onto the `ws` npm package, same public API. `loopbackPipe(router): TransportPipeFactory` connects a `createWsBackend` straight into an in-process router.
+- **Socket.IO transport** — `@jgengine/ws/socketIoPipe` (`SocketIoLikeSocket` structural type, `socketIoPipe(socket)`, `createSocketIoBackend({ socket, userId, … })`) and `@jgengine/node/socketIoServer` (`attachGameSocketIoServer({ io, host, …router options }): { rewind, close }`, structural `SocketIoLikeServer`/`SocketIoLikeServerSocket`) ride the existing ws JSON protocol over socket.io's `send`/`message` frames — no socket.io dependency in either package's types. New `socketIo({ topology?, url? })` adapter in `@jgengine/core/runtime/adapter`.
+- **WebRTC peer-to-peer** (`@jgengine/ws/peer`) — one browser tab hosts, authoritatively, with no server process. `createPeerHost({ userId, host?, runtimes?, persistence?, tickMs?, router?, rtc? })` runs a `GameHost` + `HostRouter` in the host tab (`backend` is the host player's own loopback connection, `accept(offerCode) → Promise<answerCode>` per guest); `createPeerGuest({ userId, token?, rtc? })` offers/connects from the joining side. `encodePeerSignal`/`decodePeerSignal` turn SDP into copy-pasteable base64url codes for manual cross-machine signaling; `broadcastChannelSignaling(room)` automates it for same-origin multi-tab play, with `announcePeerHost`/`joinPeerSession` wiring host/guest to a `PeerSignaling` in one call. New `p2p({ topology?, room? })` adapter (topology defaults `"private"`).
+- **LAN adapter + Fly sugar** — `lan({ topology?, port?, path? })` in `@jgengine/core/runtime/adapter` resolves through `@jgengine/shell/multiplayer`'s `resolveShellMultiplayer` to `ws(s)://<page hostname>:<port ?? 8080><path ?? /ws>` derived from `window.location`, so any browser on the LAN auto-connects to whichever machine served the page — no URL configuration. `fly({ app, topology?, path? })` is `ws` sugar for a Fly.io deploy: resolves to `wss://<app>.fly.dev<path ?? "/ws">`. `apps/dev`'s Vite server now listens on the network (`server: { host: true }`) and exposes `?p2p=host` / `?p2p=join` query params wired through the new `resolvePeerShellMultiplayer({ gameId, role, room?, userId?, feedActions? })`.
+- `ws()` (`@jgengine/core/runtime/adapter`) gained an optional `url` field, carried through by `resolveShellMultiplayer` (`args.url ?? adapter.url ?? default`).
+
+### Removed
+
+- **The `gameui` component kit** (`@jgengine/react/gameui`) — the themed HUD kit (bars, slots, feedback, meters, panels, screens, reticles, icons) and its `GameUiThemeProvider`/`useGameUiTheme` theming have been removed. **Breaking** for anyone importing `@jgengine/react/gameui` (or its subpaths/barrel). The components now ship as installable shadcn registry items at `https://jgengine.com/r/<name>.json` (`npx shadcn@latest add https://jgengine.com/r/<name>.json`), styled with Tailwind + `--jg-*` CSS variables instead of a theme object. The icon catalog (`GameIcon`, `iconForAction`, `iconForItemId`, `isGameIconName`, `GameIconName`) moved to `@jgengine/react/gameIcons`. To theme, set the `--jg-*` variables on a wrapper element (the registry's `jg-theme` presets mirror the old `ember`/`synthwave`/`fieldkit` palettes) instead of wrapping in `GameUiThemeProvider`.
+
+### Docs
+
+- Added [CREDITS.md](CREDITS.md) crediting [achrefelouafi](https://github.com/achrefelouafi) for the MIT Three.js reference projects behind the procedural building, water, rain, and snow renderers, with links from the root, `@jgengine/core`, and `@jgengine/shell` READMEs.
+
 ## 0.7.0
 
 The engine-gaps release — 22 system-level additions across turn/tactics, cards & boards,

package/dist/chat.d.ts

@@ -0,0 +1,52 @@
+import { type ReactNode } from "react";
+import type { ChatMessage } from "@jgengine/core/game/chat";
+import type { ChatSync, ChatTransport } from "@jgengine/core/multiplayer/chatContract";
+/**
+ * Lifts a callback-style ChatSync (e.g. createWsBackend().chatSyncFor(serverId))
+ * into the hook-shaped ChatTransport contract. Create once per sync — outside
+ * render or inside useMemo — so subscriptions survive re-renders.
+ */
+export declare function chatTransportFromSync(sync: ChatSync): ChatTransport;
+export declare function ChatLog({ channelId, limit, className, messageClassName, renderMessage, }: {
+    channelId: string;
+    limit?: number;
+    className?: string;
+    messageClassName?: string;
+    renderMessage?: (message: ChatMessage) => ReactNode;
+}): import("react").JSX.Element;
+export declare function ChatInput({ channelId, className, inputClassName, buttonClassName, placeholder, sendLabel, onSent, onRejected, }: {
+    channelId: string;
+    className?: string;
+    inputClassName?: string;
+    buttonClassName?: string;
+    placeholder?: string;
+    sendLabel?: ReactNode;
+    onSent?: (message: ChatMessage) => void;
+    onRejected?: (reason: string) => void;
+}): import("react").JSX.Element;
+export declare function ChannelTabs({ channels, active, onSelect, className, tabClassName, activeTabClassName, renderTab, }: {
+    channels?: readonly string[];
+    active: string;
+    onSelect: (channelId: string) => void;
+    className?: string;
+    tabClassName?: string;
+    activeTabClassName?: string;
+    renderTab?: (channelId: string, isActive: boolean) => ReactNode;
+}): import("react").JSX.Element;
+export declare function ChatPanel({ channels, initialChannel, limit, className, tabsClassName, tabClassName, activeTabClassName, logClassName, messageClassName, inputClassName, inputFieldClassName, sendButtonClassName, placeholder, renderMessage, onRejected, }: {
+    channels?: readonly string[];
+    initialChannel?: string;
+    limit?: number;
+    className?: string;
+    tabsClassName?: string;
+    tabClassName?: string;
+    activeTabClassName?: string;
+    logClassName?: string;
+    messageClassName?: string;
+    inputClassName?: string;
+    inputFieldClassName?: string;
+    sendButtonClassName?: string;
+    placeholder?: string;
+    renderMessage?: (message: ChatMessage) => ReactNode;
+    onRejected?: (reason: string) => void;
+}): import("react").JSX.Element;

package/dist/chat.js

@@ -0,0 +1,68 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useGameContext } from "./provider.js";
+import { useChat } from "./hooks.js";
+/**
+ * Lifts a callback-style ChatSync (e.g. createWsBackend().chatSyncFor(serverId))
+ * into the hook-shaped ChatTransport contract. Create once per sync — outside
+ * render or inside useMemo — so subscriptions survive re-renders.
+ */
+export function chatTransportFromSync(sync) {
+    return {
+        useMessages(channelId) {
+            const [messages, setMessages] = useState(undefined);
+            useEffect(() => {
+                if (channelId === "skip")
+                    return undefined;
+                setMessages(undefined);
+                return sync.subscribe(channelId, setMessages);
+            }, [channelId]);
+            return channelId === "skip" ? undefined : messages;
+        },
+        useActions() {
+            return useMemo(() => ({ sendMessage: (args) => sync.send(args.channelId, args.body) }), []);
+        },
+    };
+}
+export function ChatLog({ channelId, limit, className, messageClassName, renderMessage, }) {
+    const messages = useChat(channelId, limit === undefined ? undefined : { limit });
+    const scrollRef = useRef(null);
+    useEffect(() => {
+        const node = scrollRef.current;
+        if (node !== null)
+            node.scrollTop = node.scrollHeight;
+    }, [messages.length]);
+    return (_jsx("div", { ref: scrollRef, className: className, "data-chat-log": channelId, children: messages.map((message) => (_jsx("div", { className: messageClassName, "data-chat-message": true, "data-from": message.fromUserId, children: renderMessage !== undefined ? (renderMessage(message)) : (_jsxs(_Fragment, { children: [_jsx("span", { "data-chat-from": true, children: message.fromUserId }), _jsx("span", { "data-chat-body": true, children: message.body })] })) }, message.id))) }));
+}
+export function ChatInput({ channelId, className, inputClassName, buttonClassName, placeholder, sendLabel, onSent, onRejected, }) {
+    const ctx = useGameContext();
+    const [value, setValue] = useState("");
+    function submit(event) {
+        event.preventDefault();
+        const result = ctx.game.chat.send(ctx.player.userId, channelId, value);
+        if ("reason" in result) {
+            onRejected?.(result.reason);
+            return;
+        }
+        setValue("");
+        onSent?.(result.message);
+    }
+    return (_jsxs("form", { className: className, "data-chat-input": channelId, onSubmit: submit, children: [_jsx("input", { className: inputClassName, type: "text", value: value, placeholder: placeholder, onChange: (event) => setValue(event.target.value) }), _jsx("button", { type: "submit", className: buttonClassName, "data-chat-send": true, children: sendLabel ?? "Send" })] }));
+}
+export function ChannelTabs({ channels, active, onSelect, className, tabClassName, activeTabClassName, renderTab, }) {
+    const ctx = useGameContext();
+    const ids = channels ?? ctx.game.chat.channels().map((def) => def.id);
+    return (_jsx("div", { className: className, role: "tablist", "data-chat-tabs": true, children: ids.map((channelId) => {
+            const isActive = channelId === active;
+            const classes = [tabClassName, isActive ? activeTabClassName : undefined]
+                .filter(Boolean)
+                .join(" ");
+            return (_jsx("button", { type: "button", role: "tab", "aria-selected": isActive, className: classes.length > 0 ? classes : undefined, "data-channel": channelId, onClick: () => onSelect(channelId), children: renderTab !== undefined ? renderTab(channelId, isActive) : channelId }, channelId));
+        }) }));
+}
+export function ChatPanel({ channels, initialChannel, limit, className, tabsClassName, tabClassName, activeTabClassName, logClassName, messageClassName, inputClassName, inputFieldClassName, sendButtonClassName, placeholder, renderMessage, onRejected, }) {
+    const ctx = useGameContext();
+    const ids = channels ?? ctx.game.chat.channels().map((def) => def.id);
+    const [active, setActive] = useState(initialChannel ?? ids[0] ?? "global");
+    return (_jsxs("section", { className: className, "data-chat-panel": true, children: [_jsx(ChannelTabs, { channels: ids, active: active, onSelect: setActive, className: tabsClassName, tabClassName: tabClassName, activeTabClassName: activeTabClassName }), _jsx(ChatLog, { channelId: active, limit: limit, className: logClassName, messageClassName: messageClassName, renderMessage: renderMessage }), _jsx(ChatInput, { channelId: active, className: inputClassName, inputClassName: inputFieldClassName, buttonClassName: sendButtonClassName, placeholder: placeholder, onRejected: onRejected })] }));
+}

package/dist/chatBubbles.d.ts

@@ -0,0 +1,15 @@
+import type { ChatMessage } from "@jgengine/core/game/chat";
+export interface ChatBubble {
+    id: string;
+    fromUserId: string;
+    body: string;
+    at: number;
+}
+export interface ChatBubblesOptions {
+    channelId?: string;
+    ttlMs?: number;
+    limit?: number;
+}
+export declare function latestChatBubbles(messages: readonly ChatMessage[], nowMs: number, ttlMs: number): ChatBubble[];
+export declare function useChatBubbles(options?: ChatBubblesOptions): readonly ChatBubble[];
+export declare function useEntityChatBubble(instanceId: string, options?: ChatBubblesOptions): ChatBubble | null;

package/dist/chatBubbles.js

@@ -0,0 +1,45 @@
+import { useEffect, useMemo, useState } from "react";
+import { useGameStore } from "./hooks.js";
+const DEFAULT_CHAT_BUBBLE_CHANNEL = "proximity";
+const DEFAULT_CHAT_BUBBLE_TTL_MS = 4000;
+const DEFAULT_CHAT_BUBBLE_LIMIT = 8;
+const CHAT_BUBBLE_TICK_MS = 500;
+export function latestChatBubbles(messages, nowMs, ttlMs) {
+    const cutoff = nowMs - ttlMs;
+    const latestByUser = new Map();
+    for (const message of messages) {
+        if (message.at <= cutoff)
+            continue;
+        const current = latestByUser.get(message.fromUserId);
+        if (current === undefined || message.at > current.at) {
+            latestByUser.set(message.fromUserId, message);
+        }
+    }
+    return [...latestByUser.values()]
+        .sort((a, b) => a.at - b.at)
+        .map((message) => ({
+        id: message.id,
+        fromUserId: message.fromUserId,
+        body: message.body,
+        at: message.at,
+    }));
+}
+export function useChatBubbles(options) {
+    const channelId = options?.channelId ?? DEFAULT_CHAT_BUBBLE_CHANNEL;
+    const ttlMs = options?.ttlMs ?? DEFAULT_CHAT_BUBBLE_TTL_MS;
+    const limit = options?.limit ?? DEFAULT_CHAT_BUBBLE_LIMIT;
+    const messages = useGameStore((ctx) => ctx.game.chat.history(channelId, { limit }));
+    const [now, setNow] = useState(() => Date.now());
+    const hasLiveMessage = messages.some((message) => message.at > now - ttlMs);
+    useEffect(() => {
+        if (!hasLiveMessage)
+            return undefined;
+        const id = setInterval(() => setNow(Date.now()), CHAT_BUBBLE_TICK_MS);
+        return () => clearInterval(id);
+    }, [hasLiveMessage]);
+    return useMemo(() => latestChatBubbles(messages, now, ttlMs), [messages, now, ttlMs]);
+}
+export function useEntityChatBubble(instanceId, options) {
+    const bubbles = useChatBubbles(options);
+    return bubbles.find((bubble) => bubble.fromUserId === instanceId) ?? null;
+}

package/dist/components.d.ts

@@ -6,6 +6,7 @@ import { type QteStep } from "@jgengine/core/interaction/qte";
 import type { FeedEntry } from "@jgengine/core/game/feed";
 import type { StatLevelUpEvent } from "@jgengine/core/game/events";
 import { type CheckAdvantage, type CheckResult } from "@jgengine/core/stats/rollCheck";
+export { paintQteStepDom, paintSkillCheckDom } from "./skillCheckPaint.js";
 export declare function SlotGrid({ inventoryId, className, renderSlot, }: {
     inventoryId: string;
     className?: string;

package/dist/components.js

@@ -5,6 +5,8 @@ import { pendingQteStep } from "@jgengine/core/interaction/qte";
 import { rollCheck } from "@jgengine/core/stats/rollCheck";
 import { useGameContext } from "./provider.js";
 import { useCurrency, useEntityStat, useFeed, useInventory, useLocalPlayerDead } from "./hooks.js";
+import { paintQteStepDom, paintSkillCheckDom } from "./skillCheckPaint.js";
+export { paintQteStepDom, paintSkillCheckDom } from "./skillCheckPaint.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
@@ -55,45 +57,56 @@ export function DialogueBox({ dialogue, onChoice, rng, className, lineClassName,
 }
 export function SkillCheckBar({ config, startedAt, className, trackClassName, zoneClassName, markerClassName, renderStatus, }) {
     const ctx = useGameContext();
-    const [, tick] = useState(0);
+    const rootRef = useRef(null);
+    const zoneRef = useRef(null);
+    const markerRef = useRef(null);
+    const [status, setStatus] = useState(null);
+    const statusKeyRef = useRef("");
     useEffect(() => {
         let frame;
         const step = () => {
-            tick((n) => n + 1);
+            const elapsed = Math.max(0, ctx.time.now() - startedAt);
+            const result = evaluateSkillCheck(config, elapsed);
+            const root = rootRef.current;
+            const zone = zoneRef.current;
+            const marker = markerRef.current;
+            if (root !== null && zone !== null && marker !== null) {
+                paintSkillCheckDom(root, zone, marker, config, result);
+            }
+            if (renderStatus !== undefined) {
+                const key = `${result.success}:${result.timedOut}:${Math.round(result.markerPosition)}`;
+                if (key !== statusKeyRef.current) {
+                    statusKeyRef.current = key;
+                    setStatus(result);
+                }
+            }
             frame = requestAnimationFrame(step);
         };
         frame = requestAnimationFrame(step);
         return () => cancelAnimationFrame(frame);
-    }, []);
-    const elapsed = Math.max(0, ctx.time.now() - startedAt);
-    const result = evaluateSkillCheck(config, elapsed);
-    const zoneLeft = (result.zone.start / config.trackWidth) * 100;
-    const zoneWidth = ((result.zone.end - result.zone.start) / config.trackWidth) * 100;
-    const markerLeft = (result.markerPosition / config.trackWidth) * 100;
-    return (_jsxs("div", { className: className, "data-skill-check": true, "data-in-zone": result.success, "data-timed-out": result.timedOut, children: [_jsxs("div", { className: trackClassName, "data-track": true, style: { position: "relative" }, children: [_jsx("div", { className: zoneClassName, "data-zone": true, style: { position: "absolute", left: `${zoneLeft}%`, width: `${zoneWidth}%`, height: "100%" } }), _jsx("div", { className: markerClassName, "data-marker": true, style: { position: "absolute", left: `${markerLeft}%`, height: "100%" } })] }), renderStatus?.(result)] }));
+    }, [ctx, config, startedAt, renderStatus]);
+    return (_jsxs("div", { ref: rootRef, className: className, "data-skill-check": true, "data-in-zone": "false", "data-timed-out": "false", children: [_jsxs("div", { className: trackClassName, "data-track": true, style: { position: "relative" }, children: [_jsx("div", { ref: zoneRef, className: zoneClassName, "data-zone": true, style: { position: "absolute", left: "0%", width: "0%", height: "100%" } }), _jsx("div", { ref: markerRef, className: markerClassName, "data-marker": true, style: { position: "absolute", left: "0%", height: "100%" } })] }), renderStatus !== undefined && status !== null ? renderStatus(status) : null] }));
 }
 export function QteTrack({ steps, startedAt, className, stepClassName, activeClassName, doneClassName, }) {
     const ctx = useGameContext();
-    const [, tick] = useState(0);
+    const stepRefs = useRef(new Map());
     useEffect(() => {
         let frame;
         const step = () => {
-            tick((n) => n + 1);
+            const elapsed = Math.max(0, ctx.time.now() - startedAt);
+            const active = pendingQteStep(steps, elapsed);
+            paintQteStepDom(stepRefs.current, steps, elapsed, active?.id ?? null, stepClassName, activeClassName, doneClassName);
             frame = requestAnimationFrame(step);
         };
         frame = requestAnimationFrame(step);
         return () => cancelAnimationFrame(frame);
-    }, []);
-    const elapsed = Math.max(0, ctx.time.now() - startedAt);
-    const active = pendingQteStep(steps, elapsed);
-    return (_jsx("div", { className: className, "data-qte": true, children: steps.map((step) => {
-            const isActive = active?.id === step.id;
-            const isDone = elapsed > step.windowEnd;
-            const classes = [stepClassName, isActive ? activeClassName : isDone ? doneClassName : undefined]
-                .filter(Boolean)
-                .join(" ");
-            return (_jsx("div", { className: classes.length > 0 ? classes : undefined, "data-qte-step": step.id, "data-active": isActive, "data-done": isDone, children: step.action }, step.id));
-        }) }));
+    }, [ctx, steps, startedAt, stepClassName, activeClassName, doneClassName]);
+    return (_jsx("div", { className: className, "data-qte": true, children: steps.map((step) => (_jsx("div", { ref: (node) => {
+                if (node === null)
+                    stepRefs.current.delete(step.id);
+                else
+                    stepRefs.current.set(step.id, node);
+            }, className: stepClassName, "data-qte-step": step.id, "data-active": "false", "data-done": "false", children: step.action }, step.id))) }));
 }
 export function CaptureOdds({ chance, className, fillClassName, }) {
     const percent = Math.round(Math.min(1, Math.max(0, chance)) * 100);

package/dist/display.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Viewport/input-modality profile for adaptive HUDs: coarse pointer means a
+ * touchscreen is the primary input (mount touch controls, enlarge tap
+ * targets), compact means phone-scale layout — narrow width or the short
+ * height of a landscape phone (collapse side panels), portrait
+ * distinguishes the two phone orientations. Values track live media-query
+ * changes and are safe to read during SSR (everything false).
+ */
+export interface DisplayProfile {
+    coarsePointer: boolean;
+    compact: boolean;
+    portrait: boolean;
+}
+export declare function useDisplayProfile(): DisplayProfile;

package/dist/display.js

@@ -0,0 +1,45 @@
+/**
+ * Viewport/input-modality profile for adaptive HUDs: coarse pointer means a
+ * touchscreen is the primary input (mount touch controls, enlarge tap
+ * targets), compact means phone-scale layout — narrow width or the short
+ * height of a landscape phone (collapse side panels), portrait
+ * distinguishes the two phone orientations. Values track live media-query
+ * changes and are safe to read during SSR (everything false).
+ */
+import { useSyncExternalStore } from "react";
+const QUERIES = {
+    coarsePointer: "(pointer: coarse)",
+    compact: "(max-width: 820px), (max-height: 500px)",
+    portrait: "(orientation: portrait)",
+};
+const SERVER_PROFILE = { coarsePointer: false, compact: false, portrait: false };
+let cached = SERVER_PROFILE;
+function readProfile() {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function")
+        return SERVER_PROFILE;
+    const next = {
+        coarsePointer: window.matchMedia(QUERIES.coarsePointer).matches,
+        compact: window.matchMedia(QUERIES.compact).matches,
+        portrait: window.matchMedia(QUERIES.portrait).matches,
+    };
+    if (next.coarsePointer !== cached.coarsePointer ||
+        next.compact !== cached.compact ||
+        next.portrait !== cached.portrait) {
+        cached = next;
+    }
+    return cached;
+}
+function subscribe(onChange) {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function")
+        return () => undefined;
+    const lists = Object.values(QUERIES).map((query) => window.matchMedia(query));
+    for (const list of lists)
+        list.addEventListener("change", onChange);
+    return () => {
+        for (const list of lists)
+            list.removeEventListener("change", onChange);
+    };
+}
+export function useDisplayProfile() {
+    return useSyncExternalStore(subscribe, readProfile, () => SERVER_PROFILE);
+}

package/dist/dragLayer.d.ts

@@ -1,4 +1,4 @@
-import { type CSSProperties, type PointerEvent as ReactPointerEvent, type ReactNode } from "react";
+import { type CSSProperties, type PointerEvent as ReactPointerEvent, type ReactNode, type RefObject } from "react";
 import { type Cell, type Rotation } from "@jgengine/core/inventory/shapedGrid";
 export interface DragPayload<T> {
     id: string;
@@ -30,6 +30,10 @@ export interface DropInfo<T> {
 export interface DragLayer<T> {
     state: DragState<T>;
     dragging: boolean;
+    pointRef: RefObject<{
+        x: number;
+        y: number;
+    }>;
     beginDrag(payload: {
         id: string;
         value: T;
@@ -39,6 +43,7 @@ export interface DragLayer<T> {
     setTarget(target: string | null, cell?: Cell | null): void;
     endDrag(): DropInfo<T> | null;
     cancel(): void;
+    attachGhost(element: HTMLElement | null): void;
 }
 export declare function useDragLayer<T>(options?: {
     onDrop?: (info: DropInfo<T>) => void;

package/dist/dragLayer.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useCallback, useMemo, useRef, useState, } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
 import { cellFromPoint, } from "@jgengine/core/inventory/shapedGrid";
 const EMPTY_POINT = { x: 0, y: 0 };
 export function useDragLayer(options) {
@@ -10,47 +10,70 @@ export function useDragLayer(options) {
         overTarget: null,
         overCell: null,
     });
+    const pointRef = useRef(EMPTY_POINT);
+    const ghostRef = useRef(null);
     const moveRef = useRef(null);
+    const payloadRef = useRef(null);
+    const overRef = useRef({ target: null, cell: null });
     const detach = useCallback(() => {
         if (moveRef.current !== null) {
             window.removeEventListener("pointermove", moveRef.current);
             moveRef.current = null;
         }
     }, []);
+    const writeGhost = useCallback((point, rotation) => {
+        const el = ghostRef.current;
+        if (el === null)
+            return;
+        el.style.left = `${point.x}px`;
+        el.style.top = `${point.y}px`;
+        el.style.transform = `translate(-50%, -50%) rotate(${rotation * 90}deg)`;
+    }, []);
     const beginDrag = useCallback((payload, event) => {
         const point = { x: event.clientX, y: event.clientY };
+        const nextPayload = { id: payload.id, value: payload.value, rotation: payload.rotation ?? 0 };
+        payloadRef.current = nextPayload;
+        overRef.current = { target: null, cell: null };
+        pointRef.current = point;
         setState({
-            payload: { id: payload.id, value: payload.value, rotation: payload.rotation ?? 0 },
+            payload: nextPayload,
             point,
             origin: point,
             overTarget: null,
             overCell: null,
         });
+        writeGhost(point, nextPayload.rotation);
         const onMove = (moveEvent) => {
-            setState((prev) => prev.payload === null
-                ? prev
-                : { ...prev, point: { x: moveEvent.clientX, y: moveEvent.clientY } });
+            if (payloadRef.current === null)
+                return;
+            const next = { x: moveEvent.clientX, y: moveEvent.clientY };
+            pointRef.current = next;
+            writeGhost(next, payloadRef.current.rotation);
         };
         detach();
         moveRef.current = onMove;
         window.addEventListener("pointermove", onMove);
-    }, [detach]);
+    }, [detach, writeGhost]);
     const rotate = useCallback((quarterTurns = 1) => {
-        setState((prev) => prev.payload === null
-            ? prev
-            : {
-                ...prev,
-                payload: {
-                    ...prev.payload,
-                    rotation: (((prev.payload.rotation + quarterTurns) % 4) + 4) % 4,
-                },
-            });
-    }, []);
+        setState((prev) => {
+            if (prev.payload === null)
+                return prev;
+            const rotation = (((prev.payload.rotation + quarterTurns) % 4) + 4) % 4;
+            const payload = { ...prev.payload, rotation };
+            payloadRef.current = payload;
+            writeGhost(pointRef.current, rotation);
+            return { ...prev, payload, point: pointRef.current };
+        });
+    }, [writeGhost]);
     const setTarget = useCallback((target, cell = null) => {
-        setState((prev) => ({ ...prev, overTarget: target, overCell: cell }));
+        overRef.current = { target, cell };
+        setState((prev) => ({ ...prev, overTarget: target, overCell: cell, point: pointRef.current }));
     }, []);
     const reset = useCallback(() => {
         detach();
+        payloadRef.current = null;
+        overRef.current = { target: null, cell: null };
+        pointRef.current = EMPTY_POINT;
         setState({
             payload: null,
             point: EMPTY_POINT,
@@ -60,38 +83,48 @@ export function useDragLayer(options) {
         });
     }, [detach]);
     const endDrag = useCallback(() => {
+        const payload = payloadRef.current;
         let info = null;
-        setState((prev) => {
-            if (prev.payload !== null) {
-                info = {
-                    payload: prev.payload,
-                    target: prev.overTarget,
-                    cell: prev.overCell,
-                    point: prev.point,
-                };
-            }
-            return prev;
-        });
-        if (info !== null)
+        if (payload !== null) {
+            info = {
+                payload,
+                target: overRef.current.target,
+                cell: overRef.current.cell,
+                point: pointRef.current,
+            };
             options?.onDrop?.(info);
+        }
         reset();
         return info;
     }, [options, reset]);
+    const attachGhost = useCallback((element) => {
+        ghostRef.current = element;
+        if (element !== null && payloadRef.current !== null) {
+            writeGhost(pointRef.current, payloadRef.current.rotation);
+        }
+    }, [writeGhost]);
     return {
         state,
         dragging: state.payload !== null,
+        pointRef,
         beginDrag,
         rotate,
         setTarget,
         endDrag,
         cancel: reset,
+        attachGhost,
     };
 }
 export function DragGhost({ layer, className, style, children, }) {
+    const ref = useRef(null);
+    useEffect(() => {
+        layer.attachGhost(ref.current);
+        return () => layer.attachGhost(null);
+    }, [layer, layer.state.payload]);
     if (layer.state.payload === null)
         return null;
-    const { x, y } = layer.state.point;
-    return (_jsx("div", { className: className, "data-drag-ghost": "", style: {
+    const { x, y } = layer.pointRef.current;
+    return (_jsx("div", { ref: ref, className: className, "data-drag-ghost": "", style: {
             position: "fixed",
             left: x,
             top: y,

package/dist/engineStore.d.ts

@@ -6,5 +6,5 @@ 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 useEngineStore<TState, TSelected>(store: ReadableEngineStore<TState>, selector: (state: TState) => TSelected, isEqual?: (previous: TSelected, next: TSelected) => boolean): 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

@@ -1,11 +1,19 @@
 import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+import { createSelectCache, readSelectSnapshot } from "./selectSnapshot.js";
 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 useEngineStore(store, selector, isEqual = Object.is) {
+    const selectorRef = useRef(selector);
+    selectorRef.current = selector;
+    const isEqualRef = useRef(isEqual);
+    isEqualRef.current = isEqual;
+    const cacheRef = useRef(createSelectCache());
+    const subscribe = useCallback((onChange) => store.subscribe(() => onChange()), [store]);
+    const getSnapshot = useCallback(() => readSelectSnapshot(cacheRef.current, store.getState(), (state) => selectorRef.current(state), (previous, next) => isEqualRef.current(previous, next)), [store]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 }
 export function useEngineEvent(store, eventName, handler) {
     const handlerRef = useRef(handler);