@jgengine/react 0.8.0 → 0.10.0

package/dist/settings.d.ts

@@ -0,0 +1,78 @@
+import { type ReactNode } from "react";
+import { type SettingCategory, type SettingKind, type SettingOption, type SettingsStore, type SettingsSurface, type SettingsVariant, type SettingValue } from "@jgengine/core/settings/settingsModel";
+export declare function SettingsProvider({ store, children }: {
+    store: SettingsStore;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The shared settings store, or a standalone one when no provider is mounted (game code read outside the shell). */
+export declare function useSettingsStore(): SettingsStore;
+/** Read + write one persisted setting; re-renders when the value changes anywhere. */
+export declare function useSetting<T extends SettingValue>(id: string, fallback: T): readonly [T, (value: SettingValue) => void];
+/** One editable setting rendered in a settings menu category. */
+export interface SettingsRow {
+    id: string;
+    label: string;
+    kind: SettingKind;
+    value: SettingValue;
+    min?: number;
+    max?: number;
+    step?: number;
+    options?: readonly SettingOption[];
+    format?: (value: number) => string;
+    set: (value: SettingValue) => void;
+}
+/** One rebindable action row rendered in the controls settings category. */
+export interface SettingsKeybindRow {
+    action: string;
+    label: string;
+    bindingLabel: string;
+    isDefault: boolean;
+    rebind: (code: string) => void;
+    reset: () => void;
+}
+/** A settings menu category with its rows and keybinds, ready to render. */
+export interface SettingsCategoryView {
+    id: SettingCategory;
+    label: string;
+    rows: SettingsRow[];
+    keybinds: SettingsKeybindRow[];
+}
+/** A resolved game-state action — `run` is already bound to the game context and closes the menu. */
+export interface SettingsActionView {
+    id: string;
+    label: string;
+    kind: "default" | "danger";
+    description?: string;
+    run: () => void;
+}
+/** The live settings controller — every category/row/keybind/action plus open-state. Render it any way you like or drive the engine menu. */
+export interface SettingsController {
+    categories: SettingsCategoryView[];
+    /** Game-state actions (Restart, Quit…) — the menu shows them as its first "Game" tab. */
+    actions: SettingsActionView[];
+    variant: SettingsVariant;
+    surface: SettingsSurface | false;
+    isOpen: boolean;
+    open: () => void;
+    close: () => void;
+    setOpen: (open: boolean) => void;
+}
+export declare function SettingsControllerProvider({ controller, children, }: {
+    controller: SettingsController;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The engine settings controller for the current game — render your own settings UI from `categories`, or open the built-in menu with `open()`. Null-safe stub when mounted outside the shell. */
+export declare function useSettings(): SettingsController;
+/** True when the game has any setting or game-action to show — gate your own settings entry on it. */
+export declare function useHasSettings(): boolean;
+/**
+ * Inline settings entry — drop it anywhere in your game's menu or HUD; it opens
+ * the themed settings menu. Headless: pass `className` for placement/skin and
+ * `children` to replace the default gear glyph. Renders nothing when the game
+ * has no settings to show, so it never leaves a dead button behind.
+ */
+export declare function SettingsTrigger({ className, children, label, }: {
+    className?: string;
+    children?: ReactNode;
+    label?: string;
+}): import("react").JSX.Element | null;

package/dist/settings.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useSyncExternalStore } from "react";
+import { createSettingsStore, } from "@jgengine/core/settings/settingsModel";
+const SettingsStoreContext = createContext(null);
+export function SettingsProvider({ store, children }) {
+    return _jsx(SettingsStoreContext.Provider, { value: store, children: children });
+}
+/** The shared settings store, or a standalone one when no provider is mounted (game code read outside the shell). */
+export function useSettingsStore() {
+    const store = useContext(SettingsStoreContext);
+    return store ?? fallbackStore();
+}
+let standalone = null;
+function fallbackStore() {
+    if (standalone === null)
+        standalone = createSettingsStore();
+    return standalone;
+}
+/** Read + write one persisted setting; re-renders when the value changes anywhere. */
+export function useSetting(id, fallback) {
+    const store = useSettingsStore();
+    const value = useSyncExternalStore(store.subscribe, () => store.get(id, fallback), () => fallback);
+    const set = useCallback((next) => store.set(id, next), [store, id]);
+    return [value, set];
+}
+const SettingsControllerContext = createContext(null);
+export function SettingsControllerProvider({ controller, children, }) {
+    return _jsx(SettingsControllerContext.Provider, { value: controller, children: children });
+}
+/** The engine settings controller for the current game — render your own settings UI from `categories`, or open the built-in menu with `open()`. Null-safe stub when mounted outside the shell. */
+export function useSettings() {
+    return useContext(SettingsControllerContext) ?? EMPTY_CONTROLLER;
+}
+const noop = () => undefined;
+const EMPTY_CONTROLLER = {
+    categories: [],
+    actions: [],
+    variant: "panel",
+    surface: false,
+    isOpen: false,
+    open: noop,
+    close: noop,
+    setOpen: noop,
+};
+/** True when the game has any setting or game-action to show — gate your own settings entry on it. */
+export function useHasSettings() {
+    const s = useSettings();
+    return s.categories.length > 0 || s.actions.length > 0;
+}
+/**
+ * Inline settings entry — drop it anywhere in your game's menu or HUD; it opens
+ * the themed settings menu. Headless: pass `className` for placement/skin and
+ * `children` to replace the default gear glyph. Renders nothing when the game
+ * has no settings to show, so it never leaves a dead button behind.
+ */
+export function SettingsTrigger({ className, children, label = "Settings", }) {
+    const settings = useSettings();
+    if (settings.categories.length === 0 && settings.actions.length === 0)
+        return null;
+    return (_jsx("button", { type: "button", "aria-label": label, onClick: settings.open, className: className, children: children ?? (_jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 1.8, strokeLinecap: "round", strokeLinejoin: "round", width: "1em", height: "1em", "aria-hidden": true, children: [_jsx("circle", { cx: "12", cy: "12", r: "3" }), _jsx("path", { d: "M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 1 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 1 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 1 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 1 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z" })] })) }));
+}

package/dist/skillCheckPaint.d.ts

@@ -0,0 +1,4 @@
+import type { SkillCheckConfig, SkillCheckResult } from "@jgengine/core/interaction/skillCheck";
+import type { QteStep } from "@jgengine/core/interaction/qte";
+export declare function paintSkillCheckDom(root: HTMLElement, zone: HTMLElement, marker: HTMLElement, config: SkillCheckConfig, result: SkillCheckResult): void;
+export declare function paintQteStepDom(elements: ReadonlyMap<string, HTMLElement>, steps: readonly QteStep[], elapsed: number, activeId: string | null, stepClassName?: string, activeClassName?: string, doneClassName?: string): void;

package/dist/skillCheckPaint.js

@@ -0,0 +1,28 @@
+export function paintSkillCheckDom(root, zone, marker, config, result) {
+    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;
+    zone.style.left = `${zoneLeft}%`;
+    zone.style.width = `${zoneWidth}%`;
+    marker.style.left = `${markerLeft}%`;
+    root.dataset.inZone = result.success ? "true" : "false";
+    root.dataset.timedOut = result.timedOut ? "true" : "false";
+}
+export function paintQteStepDom(elements, steps, elapsed, activeId, stepClassName, activeClassName, doneClassName) {
+    for (const step of steps) {
+        const el = elements.get(step.id);
+        if (el === undefined)
+            continue;
+        const isActive = activeId === step.id;
+        const isDone = elapsed > step.windowEnd;
+        const classes = [stepClassName, isActive ? activeClassName : isDone ? doneClassName : undefined]
+            .filter(Boolean)
+            .join(" ");
+        if (classes.length > 0)
+            el.className = classes;
+        else
+            el.removeAttribute("class");
+        el.dataset.active = isActive ? "true" : "false";
+        el.dataset.done = isDone ? "true" : "false";
+    }
+}

package/dist/social.d.ts

@@ -24,7 +24,7 @@ export declare function AddFriendButton({ toUserId, className, children, onReque
     children?: ReactNode;
     onRequested?: (requestId: string) => void;
     onRejected?: (reason: string) => void;
-}): import("react").JSX.Element;
+}): import("react").JSX.Element | null;
 export declare function FriendRequestsList({ className, rowClassName, acceptClassName, declineClassName, emptyState, renderRequest, }: {
     className?: string;
     rowClassName?: string;
@@ -32,7 +32,7 @@ export declare function FriendRequestsList({ className, rowClassName, acceptClas
     declineClassName?: string;
     emptyState?: ReactNode;
     renderRequest?: (request: FriendRequestEntry) => ReactNode;
-}): import("react").JSX.Element;
+}): import("react").JSX.Element | null;
 export declare function PartyMemberRow({ member, className, dotClassName, children, }: {
     member: PartyMemberEntry;
     className?: string;
@@ -70,7 +70,7 @@ export declare function InviteToWorldButton({ toUserId, target, className, child
     children?: ReactNode;
     onInvited?: (inviteId: string) => void;
     onRejected?: (reason: string) => void;
-}): import("react").JSX.Element;
+}): import("react").JSX.Element | null;
 export declare function WorldBrowser({ listings, onJoin, className, rowClassName, joinClassName, emptyState, renderListing, }: {
     listings: readonly SessionListing[];
     onJoin: (listing: SessionListing) => void;

package/dist/social.js

@@ -18,9 +18,12 @@ export function FriendsList({ className, rowClassName, dotClassName, emptyState,
 }
 export function AddFriendButton({ toUserId, className, children, onRequested, onRejected, }) {
     const ctx = useGameContext();
-    const denied = ctx.game.social.friends.canRequest(ctx.player.userId, toUserId);
+    const social = ctx.game.social;
+    if (social === undefined)
+        return null;
+    const denied = social.friends.canRequest(ctx.player.userId, toUserId);
     return (_jsx("button", { type: "button", className: className, "data-add-friend": toUserId, disabled: denied !== null, title: denied?.reason, onClick: () => {
-            const result = ctx.game.social.friends.request(ctx.player.userId, toUserId);
+            const result = social.friends.request(ctx.player.userId, toUserId);
             if ("reason" in result)
                 onRejected?.(result.reason);
             else
@@ -30,9 +33,12 @@ export function AddFriendButton({ toUserId, className, children, onRequested, on
 export function FriendRequestsList({ className, rowClassName, acceptClassName, declineClassName, emptyState, renderRequest, }) {
     const ctx = useGameContext();
     const requests = useFriendRequests();
+    const social = ctx.game.social;
+    if (social === undefined)
+        return null;
     return (_jsx("div", { className: className, "data-friend-requests": true, children: requests.length === 0
             ? emptyState ?? null
-            : requests.map((request) => renderRequest !== undefined ? (renderRequest(request)) : (_jsxs("div", { className: rowClassName, "data-friend-request": request.requestId, children: [_jsx("span", { "data-request-from": true, children: request.fromUserId }), _jsx("button", { type: "button", className: acceptClassName, "data-accept": true, onClick: () => ctx.game.social.friends.accept(ctx.player.userId, request.requestId), children: "Accept" }), _jsx("button", { type: "button", className: declineClassName, "data-decline": true, onClick: () => ctx.game.social.friends.decline(ctx.player.userId, request.requestId), children: "Decline" })] }, request.requestId))) }));
+            : requests.map((request) => renderRequest !== undefined ? (renderRequest(request)) : (_jsxs("div", { className: rowClassName, "data-friend-request": request.requestId, children: [_jsx("span", { "data-request-from": true, children: request.fromUserId }), _jsx("button", { type: "button", className: acceptClassName, "data-accept": true, onClick: () => social.friends.accept(ctx.player.userId, request.requestId), children: "Accept" }), _jsx("button", { type: "button", className: declineClassName, "data-decline": true, onClick: () => social.friends.decline(ctx.player.userId, request.requestId), children: "Decline" })] }, request.requestId))) }));
 }
 export function PartyMemberRow({ member, className, dotClassName, children, }) {
     return (_jsxs("div", { className: className, "data-party-member": member.userId, "data-role": member.role, children: [_jsx(PresenceDot, { userId: member.userId, className: dotClassName }), _jsx("span", { "data-member-name": true, children: member.userId }), children] }));
@@ -46,33 +52,45 @@ export function PartyFrame({ className, rowClassName, dotClassName, emptyState,
 export function PartyInviteToast({ className, acceptClassName, declineClassName, renderInvite, }) {
     const ctx = useGameContext();
     const invites = usePartyInvites();
+    const social = ctx.game.social;
+    if (social === undefined)
+        return null;
     if (invites.length === 0)
         return null;
-    return (_jsx("div", { className: className, "data-party-invites": true, children: invites.map((invite) => renderInvite !== undefined ? (renderInvite(invite)) : (_jsxs("div", { "data-party-invite": invite.inviteId, children: [_jsx("span", { "data-invite-from": true, children: invite.fromUserId }), _jsx("button", { type: "button", className: acceptClassName, "data-accept": true, onClick: () => ctx.game.social.party.accept(ctx.player.userId, invite.inviteId), children: "Join" }), _jsx("button", { type: "button", className: declineClassName, "data-decline": true, onClick: () => ctx.game.social.party.decline(ctx.player.userId, invite.inviteId), children: "Decline" })] }, invite.inviteId))) }));
+    return (_jsx("div", { className: className, "data-party-invites": true, children: invites.map((invite) => renderInvite !== undefined ? (renderInvite(invite)) : (_jsxs("div", { "data-party-invite": invite.inviteId, children: [_jsx("span", { "data-invite-from": true, children: invite.fromUserId }), _jsx("button", { type: "button", className: acceptClassName, "data-accept": true, onClick: () => social.party.accept(ctx.player.userId, invite.inviteId), children: "Join" }), _jsx("button", { type: "button", className: declineClassName, "data-decline": true, onClick: () => social.party.decline(ctx.player.userId, invite.inviteId), children: "Decline" })] }, invite.inviteId))) }));
 }
 export function LeavePartyButton({ className, children, }) {
     const ctx = useGameContext();
     const members = useParty();
+    const social = ctx.game.social;
+    if (social === undefined)
+        return null;
     if (members.length === 0)
         return null;
-    return (_jsx("button", { type: "button", className: className, "data-leave-party": true, onClick: () => ctx.game.social.party.leave(ctx.player.userId), children: children ?? "Leave party" }));
+    return (_jsx("button", { type: "button", className: className, "data-leave-party": true, onClick: () => social.party.leave(ctx.player.userId), children: children ?? "Leave party" }));
 }
 export function WorldInviteToast({ className, acceptClassName, declineClassName, onAccepted, renderInvite, }) {
     const ctx = useGameContext();
     const invites = useWorldInvites();
+    const social = ctx.game.social;
+    if (social === undefined)
+        return null;
     if (invites.length === 0)
         return null;
     return (_jsx("div", { className: className, "data-world-invites": true, children: invites.map((invite) => renderInvite !== undefined ? (renderInvite(invite)) : (_jsxs("div", { "data-world-invite": invite.id, children: [_jsx("span", { "data-invite-from": true, children: invite.fromUserId }), _jsx("span", { "data-invite-server": true, children: invite.serverId }), _jsx("button", { type: "button", className: acceptClassName, "data-accept": true, onClick: () => {
-                        const result = ctx.game.social.worldInvites.accept(ctx.player.userId, invite.id);
+                        const result = social.worldInvites.accept(ctx.player.userId, invite.id);
                         if ("target" in result)
                             onAccepted(result.target);
-                    }, children: "Join" }), _jsx("button", { type: "button", className: declineClassName, "data-decline": true, onClick: () => ctx.game.social.worldInvites.decline(ctx.player.userId, invite.id), children: "Decline" })] }, invite.id))) }));
+                    }, children: "Join" }), _jsx("button", { type: "button", className: declineClassName, "data-decline": true, onClick: () => social.worldInvites.decline(ctx.player.userId, invite.id), children: "Decline" })] }, invite.id))) }));
 }
 export function InviteToWorldButton({ toUserId, target, className, children, onInvited, onRejected, }) {
     const ctx = useGameContext();
-    const denied = ctx.game.social.worldInvites.canInvite(ctx.player.userId, toUserId);
+    const social = ctx.game.social;
+    if (social === undefined)
+        return null;
+    const denied = social.worldInvites.canInvite(ctx.player.userId, toUserId);
     return (_jsx("button", { type: "button", className: className, "data-invite-to-world": toUserId, disabled: denied !== null, title: denied?.reason, onClick: () => {
-            const result = ctx.game.social.worldInvites.invite(ctx.player.userId, toUserId, target);
+            const result = social.worldInvites.invite(ctx.player.userId, toUserId, target);
             if ("reason" in result)
                 onRejected?.(result.reason);
             else
@@ -107,10 +125,13 @@ export function QuickMatchButton({ listings, onJoin, onNoMatch, filter, classNam
 }
 export function EmoteWheel({ emotes, radius, open = true, className, emoteClassName, onPlayed, onRejected, renderEmote, }) {
     const ctx = useGameContext();
+    const social = ctx.game.social;
+    if (social === undefined)
+        return null;
     if (!open)
         return null;
     return (_jsx("div", { className: className, role: "menu", "data-emote-wheel": true, "data-emote-count": emotes.length, children: emotes.map((emoteId, index) => (_jsx("button", { type: "button", role: "menuitem", className: emoteClassName, "data-emote": emoteId, "data-emote-index": index, onClick: () => {
-                const result = ctx.game.social.emotes.play(ctx.player.userId, emoteId, radius);
+                const result = social.emotes.play(ctx.player.userId, emoteId, radius);
                 if ("reason" in result)
                     onRejected?.(result.reason);
                 else