@jgengine/react 0.9.0 → 0.11.0

package/dist/chat.d.ts

@@ -23,7 +23,7 @@ export declare function ChatInput({ channelId, className, inputClassName, button
     sendLabel?: ReactNode;
     onSent?: (message: ChatMessage) => void;
     onRejected?: (reason: string) => void;
-}): import("react").JSX.Element;
+}): import("react").JSX.Element | null;
 export declare function ChannelTabs({ channels, active, onSelect, className, tabClassName, activeTabClassName, renderTab, }: {
     channels?: readonly string[];
     active: string;
@@ -32,8 +32,8 @@ export declare function ChannelTabs({ channels, active, onSelect, className, tab
     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, }: {
+}): import("react").JSX.Element | null;
+export declare function ChatPanel({ channels, initialChannel, limit, className, tabsClassName, tabClassName, activeTabClassName, logClassName, messageClassName, inputClassName, inputFieldClassName, sendButtonClassName, placeholder, renderMessage, renderTab, onRejected, }: {
     channels?: readonly string[];
     initialChannel?: string;
     limit?: number;
@@ -48,5 +48,7 @@ export declare function ChatPanel({ channels, initialChannel, limit, className,
     sendButtonClassName?: string;
     placeholder?: string;
     renderMessage?: (message: ChatMessage) => ReactNode;
+    /** Overrides a tab's label — e.g. render channel id `"proximity"` as "Nearby". */
+    renderTab?: (channelId: string, isActive: boolean) => ReactNode;
     onRejected?: (reason: string) => void;
-}): import("react").JSX.Element;
+}): import("react").JSX.Element | null;

package/dist/chat.js

@@ -37,21 +37,27 @@ export function ChatLog({ channelId, limit, className, messageClassName, renderM
 export function ChatInput({ channelId, className, inputClassName, buttonClassName, placeholder, sendLabel, onSent, onRejected, }) {
     const ctx = useGameContext();
     const [value, setValue] = useState("");
-    function submit(event) {
+    const chat = ctx.game.chat;
+    if (chat === undefined)
+        return null;
+    const submit = (event) => {
         event.preventDefault();
-        const result = ctx.game.chat.send(ctx.player.userId, channelId, value);
+        const result = 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);
+    const chat = ctx.game.chat;
+    if (chat === undefined)
+        return null;
+    const ids = channels ?? 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]
@@ -60,9 +66,12 @@ export function ChannelTabs({ channels, active, onSelect, className, tabClassNam
             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, }) {
+export function ChatPanel({ channels, initialChannel, limit, className, tabsClassName, tabClassName, activeTabClassName, logClassName, messageClassName, inputClassName, inputFieldClassName, sendButtonClassName, placeholder, renderMessage, renderTab, onRejected, }) {
     const ctx = useGameContext();
-    const ids = channels ?? ctx.game.chat.channels().map((def) => def.id);
+    const chat = ctx.game.chat;
+    const ids = channels ?? 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 })] }));
+    if (chat === undefined)
+        return null;
+    return (_jsxs("section", { className: className, "data-chat-panel": true, children: [_jsx(ChannelTabs, { channels: ids, active: active, onSelect: setActive, className: tabsClassName, tabClassName: tabClassName, activeTabClassName: activeTabClassName, renderTab: renderTab }), _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.js

@@ -4,6 +4,7 @@ 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;
+const EMPTY_CHAT_MESSAGES = [];
 export function latestChatBubbles(messages, nowMs, ttlMs) {
     const cutoff = nowMs - ttlMs;
     const latestByUser = new Map();
@@ -28,7 +29,7 @@ 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 messages = useGameStore((ctx) => ctx.game.chat?.history(channelId, { limit }) ?? EMPTY_CHAT_MESSAGES);
     const [now, setNow] = useState(() => Date.now());
     const hasLiveMessage = messages.some((message) => message.at > now - ttlMs);
     useEffect(() => {

package/dist/components.d.ts

@@ -84,6 +84,20 @@ export declare function DialogueBox({ dialogue, onChoice, rng, className, lineCl
     choiceClassName?: string;
     checkClassName?: string;
 }): import("react").JSX.Element;
+/**
+ * The id of the dialogue `ctx.game.dialogue` (or a `talkable(id)` prompt) currently has open, or `null`.
+ * The read side of the `features.dialogue` bridge — a panel looks the id up in its own dialogue catalog and
+ * renders {@link DialogueBox}, with no per-game open/close store.
+ */
+export declare function useOpenDialogueId(): string | null;
+/**
+ * Route a {@link DialogueBox} choice through the `features.dialogue` bridge: resolve the choice's invoke
+ * (honoring a skill-check `result`), run that command, and otherwise close the dialogue — the write side that
+ * replaces a per-game `onChoice` that hand-rolls `resolveDialogueInvoke` + `dialogue.close`.
+ */
+export declare function runDialogueChoice(commands: {
+    run(name: string, input?: unknown): unknown;
+}, choice: DialogueChoice, result: CheckResult | null): void;
 export declare function SkillCheckBar({ config, startedAt, className, trackClassName, zoneClassName, markerClassName, renderStatus, }: {
     config: SkillCheckConfig;
     startedAt: number;
@@ -106,6 +120,12 @@ export declare function CaptureOdds({ chance, className, fillClassName, }: {
     className?: string;
     fillClassName?: string;
 }): import("react").JSX.Element;
+/**
+ * Render `ctx.game.feed`'s entries for `action` as a newest-first toast stack — the feed-backed sibling of
+ * `@jgengine/core/game/toasts`' `createToastQueue`. Reach for this when the message source is already an engine
+ * event bound onto `ctx.game.feed` (kill feed, quest updates, loot log); reach for a `createToastQueue` when the
+ * game raises ad-hoc messages that need their own TTL independent of the feed's ring buffer.
+ */
 export declare function ToastStack({ action, limit, className, renderToast, }: {
     action: string;
     limit?: number;

package/dist/components.js

@@ -3,8 +3,10 @@ import { useEffect, useRef, useState } from "react";
 import { evaluateSkillCheck, } from "@jgengine/core/interaction/skillCheck";
 import { pendingQteStep } from "@jgengine/core/interaction/qte";
 import { rollCheck } from "@jgengine/core/stats/rollCheck";
+import { dialogueSlot } from "@jgengine/core/game/dialogue";
 import { useGameContext } from "./provider.js";
 import { useCurrency, useEntityStat, useFeed, useInventory, useLocalPlayerDead } from "./hooks.js";
+import { useStore } from "./store.js";
 import { paintQteStepDom, paintSkillCheckDom } from "./skillCheckPaint.js";
 export { paintQteStepDom, paintSkillCheckDom } from "./skillCheckPaint.js";
 export function SlotGrid({ inventoryId, className, renderSlot, }) {
@@ -30,7 +32,7 @@ export function CurrencyPill({ currencyId, className }) {
 export function ProximityPrompt({ prompt, className, }) {
     const display = prompt.display;
     if (display.kind === "keybind") {
-        return (_jsx("span", { className: className, "data-prompt": "keybind", "data-action": display.actionId, children: _jsx("kbd", { children: display.actionId }) }));
+        return (_jsxs("span", { className: className, "data-prompt": "keybind", "data-action": display.actionId, children: [_jsx("kbd", { children: display.actionId }), display.label !== undefined ? _jsx("span", { "data-prompt-label": true, children: display.label }) : null] }));
     }
     if (display.kind === "gauge") {
         return (_jsx("span", { className: className, "data-prompt": "gauge", "data-gauge": display.gaugeId, children: display.gaugeId }));
@@ -55,6 +57,26 @@ export function DialogueBox({ dialogue, onChoice, rng, className, lineClassName,
                                 ? ` (${choice.check.advantage})`
                                 : ""] }))] }, choice.label))) }, index)) : (_jsxs("p", { className: lineClassName, children: [_jsx("span", { className: speakerClassName, "data-speaker": true, children: line.speaker }), _jsx("span", { children: line.text })] }, index))) }));
 }
+/**
+ * The id of the dialogue `ctx.game.dialogue` (or a `talkable(id)` prompt) currently has open, or `null`.
+ * The read side of the `features.dialogue` bridge — a panel looks the id up in its own dialogue catalog and
+ * renders {@link DialogueBox}, with no per-game open/close store.
+ */
+export function useOpenDialogueId() {
+    return useStore(dialogueSlot, (value) => value ?? null);
+}
+/**
+ * Route a {@link DialogueBox} choice through the `features.dialogue` bridge: resolve the choice's invoke
+ * (honoring a skill-check `result`), run that command, and otherwise close the dialogue — the write side that
+ * replaces a per-game `onChoice` that hand-rolls `resolveDialogueInvoke` + `dialogue.close`.
+ */
+export function runDialogueChoice(commands, choice, result) {
+    const invoke = resolveDialogueInvoke(choice, result);
+    if (invoke !== null && invoke !== undefined)
+        commands.run(invoke.command, invoke.args ?? {});
+    else
+        commands.run("dialogue.close", {});
+}
 export function SkillCheckBar({ config, startedAt, className, trackClassName, zoneClassName, markerClassName, renderStatus, }) {
     const ctx = useGameContext();
     const rootRef = useRef(null);
@@ -119,6 +141,12 @@ function defaultToast(entry) {
     }
     return typeof entry.data === "string" ? entry.data : JSON.stringify(entry.data);
 }
+/**
+ * Render `ctx.game.feed`'s entries for `action` as a newest-first toast stack — the feed-backed sibling of
+ * `@jgengine/core/game/toasts`' `createToastQueue`. Reach for this when the message source is already an engine
+ * event bound onto `ctx.game.feed` (kill feed, quest updates, loot log); reach for a `createToastQueue` when the
+ * game raises ad-hoc messages that need their own TTL independent of the feed's ring buffer.
+ */
 export function ToastStack({ action, limit = 4, className, renderToast, }) {
     const entries = useFeed({ action, limit });
     if (entries.length === 0)

package/dist/display.d.ts

@@ -11,4 +11,5 @@ export interface DisplayProfile {
     compact: boolean;
     portrait: boolean;
 }
+/** @internal */
 export declare function useDisplayProfile(): DisplayProfile;

package/dist/display.js

@@ -40,6 +40,7 @@ function subscribe(onChange) {
             list.removeEventListener("change", onChange);
     };
 }
+/** @internal */
 export function useDisplayProfile() {
     return useSyncExternalStore(subscribe, readProfile, () => SERVER_PROFILE);
 }

package/dist/engineStore.d.ts

@@ -5,6 +5,9 @@ export interface ReadableEngineStore<TState> {
 export interface EventfulEngineStore<TEventMap extends object> {
     on<K extends keyof TEventMap>(eventName: K, listener: (payload: TEventMap[K]) => void): () => void;
 }
+/** @internal */
 export declare function useEngineState<TState>(store: ReadableEngineStore<TState>): TState;
+/** @internal */
 export declare function useEngineStore<TState, TSelected>(store: ReadableEngineStore<TState>, selector: (state: TState) => TSelected, isEqual?: (previous: TSelected, next: TSelected) => boolean): TSelected;
+/** @internal */
 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,10 +1,12 @@
 import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
 import { createSelectCache, readSelectSnapshot } from "./selectSnapshot.js";
+/** @internal */
 export function useEngineState(store) {
     const subscribe = useCallback((onChange) => store.subscribe(() => onChange()), [store]);
     const getSnapshot = useCallback(() => store.getState(), [store]);
     return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 }
+/** @internal */
 export function useEngineStore(store, selector, isEqual = Object.is) {
     const selectorRef = useRef(selector);
     selectorRef.current = selector;
@@ -15,6 +17,7 @@ export function useEngineStore(store, selector, isEqual = Object.is) {
     const getSnapshot = useCallback(() => readSelectSnapshot(cacheRef.current, store.getState(), (state) => selectorRef.current(state), (previous, next) => isEqualRef.current(previous, next)), [store]);
     return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 }
+/** @internal */
 export function useEngineEvent(store, eventName, handler) {
     const handlerRef = useRef(handler);
     handlerRef.current = handler;

package/dist/fogOverlay.d.ts

@@ -10,11 +10,14 @@ export interface FogPaintSurface {
     fillRect(x: number, y: number, width: number, height: number): void;
     clearRect(x: number, y: number, width: number, height: number): void;
 }
+/** @internal */
 export declare function forEachUnrevealedFogCell(fog: FogCells, visit: (col: number, row: number) => void): number;
+/** @internal */
 export declare function paintFogOverlay(surface: FogPaintSurface, canvasSize: {
     width: number;
     height: number;
 }, fog: FogCells, cellRect: (col: number, row: number) => FogCellRect | null, fill?: string): number;
+/** @internal */
 export declare function createFogDataUrl(fog: FogCells, canvasSize: {
     width: number;
     height: number;

package/dist/fogOverlay.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function forEachUnrevealedFogCell(fog, visit) {
     let count = 0;
     for (let row = 0; row < fog.rows; row += 1) {
@@ -10,6 +11,7 @@ export function forEachUnrevealedFogCell(fog, visit) {
     }
     return count;
 }
+/** @internal */
 export function paintFogOverlay(surface, canvasSize, fog, cellRect, fill = "rgba(11, 15, 20, 0.82)") {
     surface.clearRect(0, 0, canvasSize.width, canvasSize.height);
     surface.fillStyle = fill;
@@ -20,6 +22,7 @@ export function paintFogOverlay(surface, canvasSize, fog, cellRect, fill = "rgba
         surface.fillRect(rect.x, rect.y, rect.width, rect.height);
     });
 }
+/** @internal */
 export function createFogDataUrl(fog, canvasSize, cellRect, fill = "rgba(11, 15, 20, 0.82)") {
     if (typeof document === "undefined")
         return null;

package/dist/gameViewport.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared mobile-composition runtime. `GameViewportProvider` allocates the live
+ * game viewport once — tracking `visualViewport`, safe-area insets, orientation
+ * and layout mode — and hosts a registry every UI subsystem publishes its
+ * occupied rectangle to. HUD panels, touch-control zones, and system chrome all
+ * register here so the engine can detect forbidden overlaps instead of each
+ * subsystem independently claiming an edge.
+ */
+import { type CSSProperties, type ReactNode, type RefObject } from "react";
+import { type GameLayoutMode, type GameViewportLayout, type LayoutCollision, type LayoutRect, type LayoutRegion } from "@jgengine/core/ui/gameLayout";
+import type { LayoutOrientation } from "@jgengine/core/ui/orientation";
+import type { HudPlatform } from "@jgengine/core/ui/hudScale";
+/** A region registration: the full `LayoutRegion` plus the live element (dev outlining), rect measured by the shell/react side. */
+export interface RegionRecord extends LayoutRegion {
+    element?: HTMLElement | null;
+}
+/** A region descriptor without its measured rectangle — the caller supplies geometry through `useRegisterLayoutRegion`. */
+export type LayoutRegionSpec = Omit<LayoutRegion, "rect">;
+/** Live viewport rectangles: the layout viewport and the visible `visualViewport`. */
+export interface ViewportMetrics {
+    layout: LayoutRect;
+    visual: LayoutRect;
+}
+/** Live visible viewport, tracking `window.visualViewport` (mobile browser chrome, pinch-zoom) with a layout-viewport fallback. */
+export declare function useViewportMetrics(): ViewportMetrics;
+/**
+ * Provides the shared game viewport layout to everything it wraps. Mount it
+ * once around the whole game presentation (world, HUD, controls, system UI) so
+ * every subsystem reads one coordinated geometry and registers its rect for
+ * collision detection. Publishes live `--jg-viewport-*` / `--jg-visual-viewport-*`
+ * / `--jg-safe-*` CSS variables on its root.
+ */
+export declare function GameViewportProvider({ platforms, className, style, children, }: {
+    platforms?: readonly HudPlatform[];
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/** The live shared viewport layout. Returns a neutral default outside a `GameViewportProvider` so it never throws in previews. */
+export declare function useGameViewportLayout(): GameViewportLayout;
+/** The resolved explicit composition mode (`desktop-wide` … `mobile-portrait`). */
+export declare function useGameLayoutMode(): GameLayoutMode;
+/** The live device orientation. */
+export declare function useGameOrientation(): LayoutOrientation;
+/** Rectangles reserved by touch controls and system UI — HUD placement should avoid these. */
+export declare function useReservedControlZones(): readonly LayoutRect[];
+/** Live forbidden/warned region collisions (empty outside a provider). */
+export declare function useLayoutCollisions(): readonly LayoutCollision[];
+/**
+ * Register the element behind `ref` as a layout region and keep its measured
+ * rectangle live (ResizeObserver + viewport changes). No-op outside a
+ * `GameViewportProvider`, so a component using it still works in isolation.
+ */
+export declare function useRegisterLayoutRegion(spec: LayoutRegionSpec, ref: RefObject<HTMLElement | null>, enabled?: boolean): void;