@jgengine/react 0.6.0 → 0.8.0

package/dist/hooks.d.ts

@@ -1,13 +1,20 @@
+import { AxisChannel, type AxisChannelConfig } from "@jgengine/core/input/axisInput";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { AbilityKit, AbilitySlotSnapshot } from "@jgengine/core/combat/abilityKit";
+import type { EventMeter } from "@jgengine/core/stats/eventMeter";
 import type { GameEvents } from "@jgengine/core/game/events";
 import type { FeedEntry } from "@jgengine/core/game/feed";
 import type { QuestInstance } from "@jgengine/core/game/quest";
-import type { FriendEntry, PartyMemberEntry, PresenceInfo } from "@jgengine/core/game/social";
+import type { ChatMessage } from "@jgengine/core/game/chat";
+import type { FriendEntry, FriendRequestEntry, PartyInviteEntry, PartyMemberEntry, PresenceInfo, WorldInvite } from "@jgengine/core/game/social";
+import { type MatchFilter, type SessionListing } from "@jgengine/core/multiplayer/matchmaking";
 import type { LeaderboardScope } from "@jgengine/core/game/leaderboard";
 import type { InventorySlot } from "@jgengine/core/inventory/inventoryModel";
 import type { StatValue } from "@jgengine/core/scene/entityStats";
 import type { SceneEntity } from "@jgengine/core/scene/entityStore";
 import type { SceneObject } from "@jgengine/core/scene/objectStore";
+import type { RosterEntry } from "@jgengine/core/scene/roster";
+import type { WorldItemRecord } from "@jgengine/core/game/worldItem";
 import type { ClockSnapshot, SimClock } from "@jgengine/core/time/simClock";
 import { type PositionedPrompt } from "@jgengine/core/interaction/proximityPrompt";
 export declare function useGameStore<T>(selector: (ctx: GameContext) => T): T;
@@ -21,6 +28,9 @@ export declare function usePlayer(): {
 };
 export declare function useSceneEntities(): readonly SceneEntity[];
 export declare function useSceneObjects(): readonly SceneObject[];
+export declare function useWorldItems(): readonly WorldItemRecord[];
+/** Nearest ground item within `radius` of the local player — drives a pickup prompt/highlight. */
+export declare function useNearestWorldItem(radius: number): WorldItemRecord | null;
 export declare function useEntityStat(instanceId: string, statId: string): StatValue | null;
 export declare function useTarget(fromInstanceId: string): string | null;
 export declare function useInventory(inventoryId: string): readonly InventorySlot[];
@@ -33,6 +43,31 @@ export declare function useQuestJournal(): QuestInstance[];
 export declare function useFriends(): FriendEntry[];
 export declare function useParty(): PartyMemberEntry[];
 export declare function usePresence(userId: string): PresenceInfo;
+export declare function useWorldInvites(): WorldInvite[];
+export declare function useChat(channelId: string, options?: {
+    limit?: number;
+}): ChatMessage[];
+export declare function useFriendRequests(): FriendRequestEntry[];
+export declare function usePartyInvites(): PartyInviteEntry[];
+export interface WorldBrowserState {
+    listings: SessionListing[];
+    loading: boolean;
+    error: string | null;
+    refresh(): void;
+}
+/**
+ * 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 declare function useWorldBrowser(options: {
+    fetchSessions: () => Promise<readonly SessionListing[]>;
+    filter?: MatchFilter;
+    limit?: number;
+    refreshMs?: number;
+}): WorldBrowserState;
+export declare function useRoster(userId?: string): readonly RosterEntry[];
 export declare function useLeaderboard(stat: string, options: {
     scope: LeaderboardScope;
     limit?: number;
@@ -46,3 +81,37 @@ export declare function useGameClock(): ClockSnapshot & {
     controls: SimClock;
 };
 export declare function useActivePrompt<T extends PositionedPrompt>(prompts?: readonly T[]): T | null;
+export interface AbilitySlotBindingOptions {
+    intervalMs?: number;
+}
+export declare function useAbilitySlots(kit: AbilityKit, resourceAvailable?: number, options?: AbilitySlotBindingOptions): AbilitySlotSnapshot[];
+export declare function useAbilitySlot(kit: AbilityKit, slotId: string, resourceAvailable?: number, options?: AbilitySlotBindingOptions): AbilitySlotSnapshot | null;
+export interface EventMeterView {
+    value: number;
+    fraction: number;
+    tier: string | null;
+    ready: boolean;
+}
+export declare function useEventMeter(meter: EventMeter, options?: AbilitySlotBindingOptions): EventMeterView;
+type HeldKeyEventTarget = Pick<Window, "addEventListener" | "removeEventListener">;
+export declare function createHeldKeyTracker(target: HeldKeyEventTarget): {
+    isDown: (code: string) => boolean;
+    dispose: () => void;
+};
+/**
+ * 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 declare function useHeldKeys(): (code: string) => boolean;
+export interface UseAxisChannelResult {
+    channel: AxisChannel;
+    isDown: (code: string) => boolean;
+}
+/**
+ * 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 declare function useAxisChannel(config: AxisChannelConfig): UseAxisChannelResult;
+export {};

package/dist/hooks.js

@@ -1,4 +1,6 @@
-import { useMemo, 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 { useGameContext } from "./provider.js";
 export function useGameStore(selector) {
@@ -20,6 +22,19 @@ export function useSceneEntities() {
 export function useSceneObjects() {
     return useGameStore((ctx) => ctx.scene.object.list());
 }
+export function useWorldItems() {
+    return useGameStore((ctx) => ctx.scene.worldItem.list());
+}
+/** Nearest ground item within `radius` of the local player — drives a pickup prompt/highlight. */
+export function useNearestWorldItem(radius) {
+    return useGameStore((ctx) => {
+        const player = localPlayerEntity(ctx);
+        if (player === null)
+            return null;
+        const instanceId = ctx.scene.worldItem.nearestInRadius(player.position, radius);
+        return instanceId === null ? null : ctx.scene.worldItem.get(instanceId);
+    });
+}
 export function useEntityStat(instanceId, statId) {
     return useGameStore((ctx) => ctx.scene.entity.stats.get(instanceId, statId));
 }
@@ -47,6 +62,66 @@ 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));
+}
 export function useLeaderboard(stat, options) {
     return useGameStore((ctx) => ctx.game.leaderboard.getTop(stat, options));
 }
@@ -79,3 +154,73 @@ 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);
+    const [, setTick] = useState(0);
+    useEffect(() => {
+        if (intervalMs <= 0 || typeof window === "undefined")
+            return undefined;
+        const id = window.setInterval(() => setTick((current) => current + 1), intervalMs);
+        return () => window.clearInterval(id);
+    }, [intervalMs]);
+}
+export function useAbilitySlots(kit, resourceAvailable, options) {
+    useEngineHeartbeat(options?.intervalMs ?? 80);
+    return kit.snapshot(resourceAvailable);
+}
+export function useAbilitySlot(kit, slotId, resourceAvailable, options) {
+    useEngineHeartbeat(options?.intervalMs ?? 80);
+    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() };
+}
+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/identity.d.ts

@@ -0,0 +1,65 @@
+import { type ReactNode } from "react";
+import { type AuthSession, type PlayerIdentity } from "@jgengine/core/multiplayer/identity";
+export interface IdentitySource {
+    session: AuthSession | null;
+    isLoading: boolean;
+    signOut?: () => void;
+}
+export interface ClerkUserShape {
+    id: string;
+    fullName?: string | null;
+    username?: string | null;
+    imageUrl?: string | null;
+    primaryEmailAddress?: {
+        emailAddress: string;
+    } | null;
+    createdAt?: Date | null;
+    lastSignInAt?: Date | null;
+}
+export interface ClerkUserState {
+    isLoaded: boolean;
+    isSignedIn: boolean | undefined;
+    user: ClerkUserShape | null | undefined;
+}
+export declare function clerkIdentity(state: ClerkUserState, options?: {
+    signOut?: () => void;
+}): IdentitySource;
+export interface BetterAuthUserShape {
+    id: string;
+    name?: string | null;
+    email?: string | null;
+    image?: string | null;
+}
+export interface BetterAuthSessionState {
+    data: {
+        user: BetterAuthUserShape;
+    } | null | undefined;
+    isPending: boolean;
+}
+export declare function betterAuthIdentity(state: BetterAuthSessionState, options?: {
+    signOut?: () => void;
+}): IdentitySource;
+export declare function guestIdentity(seed?: string): IdentitySource;
+export declare function GameIdentityProvider({ source, children, }: {
+    source: IdentitySource;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function useSession(): IdentitySource;
+export declare function useAuthedPlayer(options?: {
+    guestSeed?: string;
+}): PlayerIdentity | null;
+export declare function RequireSession({ fallback, loading, children, }: {
+    fallback?: ReactNode;
+    loading?: ReactNode;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function UserBadge({ className, avatarClassName, nameClassName, renderBadge, }: {
+    className?: string;
+    avatarClassName?: string;
+    nameClassName?: string;
+    renderBadge?: (session: AuthSession) => ReactNode;
+}): import("react").JSX.Element | null;
+export declare function SignOutButton({ className, children, }: {
+    className?: string;
+    children?: ReactNode;
+}): import("react").JSX.Element | null;

package/dist/identity.js

@@ -0,0 +1,94 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { resolveGuestSession, sessionPlayer, } from "@jgengine/core/multiplayer/identity";
+export function clerkIdentity(state, options) {
+    if (!state.isLoaded)
+        return { session: null, isLoading: true };
+    const user = state.user;
+    if (state.isSignedIn !== true || user === null || user === undefined) {
+        return { session: null, isLoading: false };
+    }
+    const displayName = user.fullName ?? user.username ?? undefined;
+    const session = { userId: user.id };
+    if (displayName !== undefined)
+        session.displayName = displayName;
+    if (user.imageUrl !== null && user.imageUrl !== undefined)
+        session.avatarUrl = user.imageUrl;
+    const email = user.primaryEmailAddress?.emailAddress;
+    if (email !== undefined)
+        session.email = email;
+    if (user.createdAt !== null && user.createdAt !== undefined) {
+        session.isNew =
+            user.lastSignInAt === null ||
+                user.lastSignInAt === undefined ||
+                user.lastSignInAt.getTime() <= user.createdAt.getTime();
+    }
+    const source = { session, isLoading: false };
+    if (options?.signOut !== undefined)
+        source.signOut = options.signOut;
+    return source;
+}
+export function betterAuthIdentity(state, options) {
+    if (state.isPending)
+        return { session: null, isLoading: true };
+    const user = state.data?.user;
+    if (user === undefined)
+        return { session: null, isLoading: false };
+    const session = { userId: user.id };
+    if (user.name !== null && user.name !== undefined)
+        session.displayName = user.name;
+    if (user.image !== null && user.image !== undefined)
+        session.avatarUrl = user.image;
+    if (user.email !== null && user.email !== undefined)
+        session.email = user.email;
+    const source = { session, isLoading: false };
+    if (options?.signOut !== undefined)
+        source.signOut = options.signOut;
+    return source;
+}
+export function guestIdentity(seed) {
+    return { session: resolveGuestSession(seed), isLoading: false };
+}
+const IdentityReactContext = createContext(null);
+export function GameIdentityProvider({ source, children, }) {
+    return _jsx(IdentityReactContext.Provider, { value: source, children: children });
+}
+export function useSession() {
+    const source = useContext(IdentityReactContext);
+    if (source === null)
+        throw new Error("useSession must be used within <GameIdentityProvider>");
+    return source;
+}
+export function useAuthedPlayer(options) {
+    const { session, isLoading } = useSession();
+    const guestSeed = options?.guestSeed;
+    return useMemo(() => {
+        if (session !== null)
+            return sessionPlayer(session);
+        if (isLoading || guestSeed === undefined)
+            return null;
+        return sessionPlayer(resolveGuestSession(guestSeed));
+    }, [session, isLoading, guestSeed]);
+}
+export function RequireSession({ fallback, loading, children, }) {
+    const { session, isLoading } = useSession();
+    if (isLoading)
+        return _jsx(_Fragment, { children: loading ?? null });
+    if (session === null)
+        return _jsx(_Fragment, { children: fallback ?? null });
+    return _jsx(_Fragment, { children: children });
+}
+export function UserBadge({ className, avatarClassName, nameClassName, renderBadge, }) {
+    const { session } = useSession();
+    if (session === null)
+        return null;
+    if (renderBadge !== undefined)
+        return _jsx(_Fragment, { children: renderBadge(session) });
+    return (_jsxs("span", { className: className, "data-user": session.userId, children: [session.avatarUrl !== undefined && (_jsx("img", { className: avatarClassName, src: session.avatarUrl, alt: "", "data-avatar": true })), _jsx("span", { className: nameClassName, "data-display-name": true, children: session.displayName ?? session.userId })] }));
+}
+export function SignOutButton({ className, children, }) {
+    const { session, signOut } = useSession();
+    if (session === null || signOut === undefined)
+        return null;
+    return (_jsx("button", { type: "button", className: className, "data-sign-out": true, onClick: () => signOut(), children: children ?? "Sign out" }));
+}

package/dist/index.d.ts

@@ -1,4 +1,11 @@
 export * from "./provider.js";
+export * from "./identity.js";
+export * from "./chat.js";
+export * from "./voice.js";
+export * from "./social.js";
 export * from "./hooks.js";
 export * from "./components.js";
 export * from "./engineStore.js";
+export * from "./dragLayer.js";
+export * from "./display.js";
+export * from "./map.js";

package/dist/index.js

@@ -1,4 +1,11 @@
 export * from "./provider.js";
+export * from "./identity.js";
+export * from "./chat.js";
+export * from "./voice.js";
+export * from "./social.js";
 export * from "./hooks.js";
 export * from "./components.js";
 export * from "./engineStore.js";
+export * from "./dragLayer.js";
+export * from "./display.js";
+export * from "./map.js";

package/dist/map.d.ts

@@ -0,0 +1,68 @@
+import { type ReactNode } from "react";
+import type { FogField } from "@jgengine/core/world/fog";
+import { type MapMarker, type MarkerKindStyle, type MarkerSet } from "@jgengine/core/world/markers";
+import { type WorldXZ } from "@jgengine/core/world/minimap";
+export declare function useMarkers(markers: MarkerSet): readonly MapMarker[];
+export declare function useFog(fog: FogField): ReturnType<FogField["cells"]>;
+export interface MinimapProps {
+    markers: MarkerSet;
+    center: WorldXZ;
+    worldRadius: number;
+    fog?: FogField;
+    size?: number;
+    heading?: number;
+    rotate?: boolean;
+    kindStyles?: Record<string, MarkerKindStyle>;
+    background?: string;
+    /** World bounds the `background` image spans, so it pans correctly under a player-centered map. */
+    mapBounds?: MapBounds;
+    className?: string;
+    title?: string;
+    children?: ReactNode;
+}
+export interface MapBounds {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+}
+/**
+ * Framed circular minimap: optional baked terrain background, reveal-on-event
+ * fog overlay, categorized marker icons, and a facing arrow. Reads a core
+ * `MarkerSet` / `FogField`; supply your own `kindStyles` palette to reskin.
+ */
+export declare function Minimap({ markers, center, worldRadius, fog, size, heading, rotate, kindStyles, background, mapBounds, className, title, children, }: MinimapProps): ReactNode;
+export interface CompassProps {
+    heading: number;
+    center?: WorldXZ;
+    markers?: MarkerSet;
+    width?: number;
+    fov?: number;
+    kindStyles?: Record<string, MarkerKindStyle>;
+    className?: string;
+}
+/**
+ * Horizontal compass strip centered on the player's facing bearing, with the
+ * eight cardinals and optional marker pips (bearing to each `MarkerSet` entry).
+ */
+export declare function Compass({ heading, center, markers, width, fov, kindStyles, className, }: CompassProps): ReactNode;
+export interface WorldMapProps {
+    markers: MarkerSet;
+    bounds: MapBounds;
+    player?: WorldXZ;
+    heading?: number;
+    fog?: FogField;
+    background?: string;
+    width?: number;
+    height?: number;
+    kindStyles?: Record<string, MarkerKindStyle>;
+    className?: string;
+    title?: string;
+    onClose?: () => void;
+}
+/**
+ * Full-bounds top-down world map (the "press M" overlay): baked terrain
+ * background, reveal-on-event fog, all markers with labels, and the player.
+ * Rectangular linear projection over the supplied world `bounds`.
+ */
+export declare function WorldMap({ markers, bounds, player, heading, fog, background, width, height, kindStyles, className, title, onClose, }: WorldMapProps): ReactNode;