@jgengine/react 0.7.0 → 0.9.0

package/dist/hooks.js

@@ -1,10 +1,19 @@
-import { useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { AxisChannel } from "@jgengine/core/input/axisInput";
+import { browseSessions, } from "@jgengine/core/multiplayer/matchmaking";
 import { resolveActivePrompt, } from "@jgengine/core/interaction/proximityPrompt";
+import { gamePhase, setGamePhase } from "@jgengine/core/game/gamePhase";
 import { useGameContext } from "./provider.js";
-export function useGameStore(selector) {
+import { createSelectCache, readSelectSnapshot } from "./selectSnapshot.js";
+export function useGameStore(selector, isEqual = Object.is) {
     const ctx = useGameContext();
-    useSyncExternalStore(ctx.subscribe, ctx.version, ctx.version);
-    return selector(ctx);
+    const selectorRef = useRef(selector);
+    selectorRef.current = selector;
+    const isEqualRef = useRef(isEqual);
+    isEqualRef.current = isEqual;
+    const cacheRef = useRef(createSelectCache());
+    const getSnapshot = useCallback(() => readSelectSnapshot(cacheRef.current, ctx.version(), () => selectorRef.current(ctx), (previous, next) => isEqualRef.current(previous, next)), [ctx]);
+    return useSyncExternalStore(ctx.subscribe, getSnapshot, getSnapshot);
 }
 export function useGame() {
     const ctx = useGameContext();
@@ -14,6 +23,13 @@ export function usePlayer() {
     const ctx = useGameContext();
     return useMemo(() => ({ userId: ctx.player.userId, isNew: ctx.player.isNew }), [ctx]);
 }
+/** Live run phase + a setter that also gates the shell's touch controls. `menu`/`paused`/`ended` hide the touch dock; `playing` shows it. */
+export function useGamePhase() {
+    const ctx = useGameContext();
+    const phase = useGameStore((c) => gamePhase(c));
+    const setPhase = useCallback((next) => setGamePhase(ctx, next), [ctx]);
+    return { phase, setPhase };
+}
 export function useSceneEntities() {
     return useGameStore((ctx) => ctx.scene.entity.list());
 }
@@ -60,6 +76,63 @@ export function useParty() {
 export function usePresence(userId) {
     return useGameStore((ctx) => ctx.game.social.presence.get(userId));
 }
+export function useWorldInvites() {
+    return useGameStore((ctx) => ctx.game.social.worldInvites.listFor(ctx.player.userId));
+}
+export function useChat(channelId, options) {
+    const limit = options?.limit ?? 50;
+    return useGameStore((ctx) => ctx.game.chat.history(channelId, { limit, viewerUserId: ctx.player.userId }));
+}
+export function useFriendRequests() {
+    return useGameStore((ctx) => ctx.game.social.friends.requestsFor(ctx.player.userId));
+}
+export function usePartyInvites() {
+    return useGameStore((ctx) => ctx.game.social.party.invitesFor(ctx.player.userId));
+}
+/**
+ * Polls a host-supplied session fetcher (e.g. createWsBackend().browse) and
+ * filters through matchmaking's browseSessions. fetchSessions must be
+ * identity-stable (wrap in useCallback at the call site) or every render
+ * refetches.
+ */
+export function useWorldBrowser(options) {
+    const { fetchSessions, refreshMs } = options;
+    const [raw, setRaw] = useState([]);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const [refreshTick, setRefreshTick] = useState(0);
+    useEffect(() => {
+        let cancelled = false;
+        setLoading(true);
+        fetchSessions()
+            .then((listings) => {
+            if (cancelled)
+                return;
+            setRaw(listings);
+            setError(null);
+            setLoading(false);
+        })
+            .catch((cause) => {
+            if (cancelled)
+                return;
+            setError(cause instanceof Error ? cause.message : "failed to browse sessions");
+            setLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [fetchSessions, refreshTick]);
+    useEffect(() => {
+        if (refreshMs === undefined || refreshMs <= 0)
+            return undefined;
+        const id = setInterval(() => setRefreshTick((tick) => tick + 1), refreshMs);
+        return () => clearInterval(id);
+    }, [refreshMs]);
+    const filter = options.filter;
+    const limit = options.limit;
+    const listings = useMemo(() => browseSessions(raw, filter, limit === undefined ? {} : { limit }), [raw, filter, limit]);
+    return useMemo(() => ({ listings, loading, error, refresh: () => setRefreshTick((tick) => tick + 1) }), [listings, loading, error]);
+}
 export function useRoster(userId) {
     return useGameStore((ctx) => ctx.game.roster.list(userId ?? ctx.player.userId));
 }
@@ -95,26 +168,111 @@ export function useActivePrompt(prompts) {
         return resolveActivePrompt({ x: player.position[0], z: player.position[2] }, prompts);
     });
 }
-function useEngineHeartbeat(intervalMs) {
-    const ctx = useGameContext();
-    useSyncExternalStore(ctx.subscribe, ctx.version, ctx.version);
+export function abilityKitNeedsHeartbeat(kit, resourceAvailable) {
+    for (const slot of kit.snapshot(resourceAvailable)) {
+        if (slot.cooldownRemainingMs > 0 || slot.justCast || slot.groupRemainingMs > 0)
+            return true;
+    }
+    return false;
+}
+export function eventMeterNeedsHeartbeat(meter, previous) {
+    const next = {
+        value: meter.value(),
+        fraction: meter.fraction(),
+        tier: meter.tier(),
+        ready: meter.ready(),
+    };
+    if (previous === null)
+        return true;
+    return (previous.value !== next.value ||
+        previous.fraction !== next.fraction ||
+        previous.tier !== next.tier ||
+        previous.ready !== next.ready);
+}
+function useEngineHeartbeat(intervalMs, shouldTick) {
     const [, setTick] = useState(0);
+    const shouldTickRef = useRef(shouldTick);
+    shouldTickRef.current = shouldTick;
     useEffect(() => {
         if (intervalMs <= 0 || typeof window === "undefined")
             return undefined;
-        const id = window.setInterval(() => setTick((current) => current + 1), intervalMs);
+        const id = window.setInterval(() => {
+            if (shouldTickRef.current())
+                setTick((current) => current + 1);
+        }, intervalMs);
         return () => window.clearInterval(id);
     }, [intervalMs]);
 }
 export function useAbilitySlots(kit, resourceAvailable, options) {
-    useEngineHeartbeat(options?.intervalMs ?? 80);
+    useEngineHeartbeat(options?.intervalMs ?? 80, () => abilityKitNeedsHeartbeat(kit, resourceAvailable));
     return kit.snapshot(resourceAvailable);
 }
 export function useAbilitySlot(kit, slotId, resourceAvailable, options) {
-    useEngineHeartbeat(options?.intervalMs ?? 80);
+    useEngineHeartbeat(options?.intervalMs ?? 80, () => abilityKitNeedsHeartbeat(kit, resourceAvailable));
     return kit.state(slotId, resourceAvailable);
 }
 export function useEventMeter(meter, options) {
-    useEngineHeartbeat(options?.intervalMs ?? 80);
-    return { value: meter.value(), fraction: meter.fraction(), tier: meter.tier(), ready: meter.ready() };
+    const previous = useRef(null);
+    useEngineHeartbeat(options?.intervalMs ?? 80, () => {
+        const changed = eventMeterNeedsHeartbeat(meter, previous.current);
+        if (changed) {
+            previous.current = {
+                value: meter.value(),
+                fraction: meter.fraction(),
+                tier: meter.tier(),
+                ready: meter.ready(),
+            };
+        }
+        return changed;
+    });
+    const view = { value: meter.value(), fraction: meter.fraction(), tier: meter.tier(), ready: meter.ready() };
+    previous.current = view;
+    return view;
+}
+export function createHeldKeyTracker(target) {
+    const held = new Set();
+    const onKeyDown = (event) => held.add(event.code);
+    const onKeyUp = (event) => held.delete(event.code);
+    const onBlur = () => held.clear();
+    target.addEventListener("keydown", onKeyDown);
+    target.addEventListener("keyup", onKeyUp);
+    target.addEventListener("blur", onBlur);
+    return {
+        isDown: (code) => held.has(code),
+        dispose: () => {
+            target.removeEventListener("keydown", onKeyDown);
+            target.removeEventListener("keyup", onKeyUp);
+            target.removeEventListener("blur", onBlur);
+            held.clear();
+        },
+    };
+}
+/**
+ * Held-key predicate backed by window keydown/keyup/blur listeners (blur clears held state so a
+ * released-off-window key doesn't stick). SSR-safe: listeners attach in an effect, never at module
+ * scope. The returned predicate is stable across renders.
+ */
+export function useHeldKeys() {
+    const trackerRef = useRef(null);
+    useEffect(() => {
+        if (typeof window === "undefined")
+            return undefined;
+        const tracker = createHeldKeyTracker(window);
+        trackerRef.current = tracker;
+        return () => {
+            tracker.dispose();
+            trackerRef.current = null;
+        };
+    }, []);
+    return useCallback((code) => trackerRef.current?.isDown(code) ?? false, []);
+}
+/**
+ * Wires useHeldKeys into a fresh AxisChannel, ready for a per-frame `channel.sample(dt, isDown)`.
+ * The channel is recreated when `config` identity changes, so pass a stable config (useMemo/module
+ * constant at the call site) unless a rebind is intended.
+ */
+export function useAxisChannel(config) {
+    const isDown = useHeldKeys();
+    const channel = useMemo(() => new AxisChannel(config), [config]);
+    return { channel, isDown };
 }

package/dist/hudLayout.d.ts

@@ -0,0 +1,61 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type HudAnchor, type HudLayoutStore } from "@jgengine/core/ui/hudLayout";
+/**
+ * How a panel behaves on compact (phone-scale) displays. `keep` stays visible
+ * at the global compact scale, `chip` collapses to a small tap-to-expand
+ * pill, `hide` unmounts entirely.
+ */
+export type HudCompactMode = "keep" | "chip" | "hide";
+export interface HudEditChord {
+    hold: string;
+    press: string;
+}
+export declare function useHudLayout(options?: {
+    storageKey?: string;
+    snap?: number;
+    locked?: boolean;
+}): HudLayoutStore;
+/**
+ * Full-viewport HUD surface. Panels declared with `HudPanel` flow into nine
+ * anchor regions and stack automatically with a gap — no per-panel pixel
+ * offsets, no manual clearance for sibling panels, the touch-control dock
+ * (`--jg-hud-dock-clearance`), or device safe areas. On compact displays the
+ * whole surface scales down and each panel applies its `compact` behavior.
+ */
+export declare function HudCanvas({ layout, editChord, compactScale, className, style, children, }: {
+    layout: HudLayoutStore;
+    editChord?: HudEditChord | false;
+    /** Zoom applied to the whole HUD on compact displays. Default 0.85. */
+    compactScale?: number;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * A HUD block that lives in one of the nine anchor regions. Panels sharing a
+ * region stack outward from the screen edge in ascending `order`. On fine
+ * pointers panels stay draggable through the edit chord; a dragged panel
+ * leaves the flow and keeps its custom placement. On compact displays custom
+ * placements are ignored and the `compact` behavior applies.
+ */
+export declare function HudPanel({ id, anchor, order, compact: compactMode, chip, interactive, inset, locked, className, style, children, }: {
+    id: string;
+    anchor?: HudAnchor;
+    /** Stack position within the region, ascending outward from the screen edge. Default 0. */
+    order?: number;
+    /** Behavior on compact displays. Default `"keep"`. */
+    compact?: HudCompactMode;
+    /** Chip label when `compact="chip"`. Defaults to the panel id. */
+    chip?: string;
+    /** `false` lets pointer events pass through to the game (read-only panels). Default true. */
+    interactive?: boolean;
+    /** Legacy pixel inset from the anchor; only used as the reset placement for dragged panels. */
+    inset?: {
+        x: number;
+        y: number;
+    };
+    locked?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}): import("react").JSX.Element | null;