@jgengine/react 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -11,7 +11,27 @@ 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.10.0
+
+### Migrate
+
+- **Nothing to change for existing games** — the shared mobile-composition system (viewport allocation, region collision, `--jg-*` viewport vars) is wired automatically by the shell for every game; `HudPanel`s inside a `HudCanvas` register themselves. Legacy `orientation: "landscape" | "portrait"` keeps its advisory dismissible-hint behavior unchanged.
+- **Opt a driving/landscape game into the strict gate**: replace the advisory `orientation` with the contract form — `orientation: { mobile: "landscape-required" }` (rules: `any` · `portrait`/`landscape` advisory · `portrait-required`/`landscape-required` · `unsupported`). In portrait the engine now shows a polished `RotateDeviceScreen`, suppresses input, freezes the sim, and unmounts the HUD/controls until the device is landscape.
+- **Declare HUD intent** where useful: `HudPanel` gains `priority` (`critical`/`secondary`/`tertiary`), `mobileBehavior` (`hidden` unmounts on phones, `transient` softens collision, …), `allowOverlapWith`, and `collisionGroup`. Optional — omitting them keeps prior behavior.
+- **Mobile validation now also fails on overlap**: `bun run shoot <game> --device mobile|mobile-landscape|both` exits non-zero on forbidden inter-element collisions (not just viewport overflow), naming both regions.
+
+### Added
+
+- Shared mobile layout composition — `@jgengine/core/ui/gameLayout` (pure geometry: `resolveLayoutMode`, `intersects`, `overlapArea`, `detectLayoutCollisions`, `computeGameplayRect`, `LayoutRegion`, `GameViewportLayout`) and `@jgengine/core/ui/orientation` (`resolveOrientationRequirement`, `orientationGateActive`, `MobileOrientationRule`). `@jgengine/react` adds `GameViewportProvider` (mounted by the shell), hooks (`useGameViewportLayout`, `useGameLayoutMode`, `useGameOrientation`, `useReservedControlZones`, `useLayoutCollisions`, `useRegisterLayoutRegion`), and a headless `RotateDeviceScreen`. The provider tracks `window.visualViewport`, publishes `--jg-viewport-*` / `--jg-visual-viewport-*` / `--jg-safe-*` CSS vars, resolves the explicit layout mode, and detects forbidden region overlaps (dev `data-jg-layout-collision` + console diagnostic).
+- Mandatory orientation contract — `PlayableGame.orientation` accepts `{ mobile: <rule> }`; `landscape-required`/`portrait-required` render an engine-owned rotate gate that blocks gameplay (input suppressed, simulation frozen, HUD/controls unmounted), self-correcting when the device is turned. Reduced-motion and safe-area respected; `visualViewport`-sized for mobile Safari/PWA.
+- Reserved touch-control zones — the touch dock registers its joystick / action-cluster / utility rectangles (runtime-measured) as `control` regions, so HUD placement and collision validation know exactly where controls sit.
+- HUD placement metadata — `HudPanel` gains `priority`, `mobileBehavior`, `allowOverlapWith`, `collisionGroup`, and registers as a collision-tracked layout region.
+- Mobile-landscape shoot device — `bun run shoot --device mobile-landscape` (844×390) plus collision-gate reads that fail mobile validation on forbidden overlaps.
+- Canyon Chase migrated as the reference landscape-required game — declares `orientation: { mobile: "landscape-required" }`, composes its HUD through coordinated `HudPanel` regions (pursuit distance critical, border secondary, survey map hidden on mobile, radio transient) instead of independent fixed corners.
+
+### Changed
+
+- First-person projectile tracers now originate from the weapon muzzle instead of the camera/eye centerline. Hit detection is unchanged (still crosshair-accurate) — only the drawn tracer's start point moved to the viewmodel muzzle, which tracks full aim yaw and pitch. Non-viewmodel games and enemy tracers are unaffected.
 
 ## 0.9.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,7 +32,7 @@ export declare function ChannelTabs({ channels, active, onSelect, className, tab
     tabClassName?: string;
     activeTabClassName?: string;
     renderTab?: (channelId: string, isActive: boolean) => ReactNode;
-}): import("react").JSX.Element;
+}): import("react").JSX.Element | null;
 export declare function ChatPanel({ channels, initialChannel, limit, className, tabsClassName, tabClassName, activeTabClassName, logClassName, messageClassName, inputClassName, inputFieldClassName, sendButtonClassName, placeholder, renderMessage, onRejected, }: {
     channels?: readonly string[];
     initialChannel?: string;
@@ -49,4 +49,4 @@ export declare function ChatPanel({ channels, initialChannel, limit, className,
     placeholder?: string;
     renderMessage?: (message: ChatMessage) => 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]
@@ -62,7 +68,10 @@ export function ChannelTabs({ channels, active, onSelect, className, tabClassNam
 }
 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 chat = ctx.game.chat;
+    const ids = channels ?? chat?.channels().map((def) => def.id) ?? [];
     const [active, setActive] = useState(initialChannel ?? ids[0] ?? "global");
+    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 }), _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.js

@@ -30,7 +30,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 }));

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;

package/dist/gameViewport.js

@@ -0,0 +1,340 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 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 { createContext, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
+import { computeGameplayRect, detectLayoutCollisions, formatLayoutCollisions, resolveLayoutMode, orientationOf, } from "@jgengine/core/ui/gameLayout";
+import { useDisplayProfile } from "./display.js";
+function sameRect(a, b) {
+    return a.left === b.left && a.top === b.top && a.right === b.right && a.bottom === b.bottom;
+}
+function sameRegion(a, b) {
+    return (a.kind === b.kind &&
+        a.collisionPolicy === b.collisionPolicy &&
+        a.priority === b.priority &&
+        a.collisionGroup === b.collisionGroup &&
+        a.element === b.element &&
+        (a.allowOverlapWith ?? []).join("+") === (b.allowOverlapWith ?? []).join("+") &&
+        sameRect(a.rect, b.rect));
+}
+const EMPTY_REGIONS = [];
+function createRegionRegistry() {
+    const records = new Map();
+    const listeners = new Set();
+    let snapshot = EMPTY_REGIONS;
+    let frame = 0;
+    const flush = () => {
+        frame = 0;
+        for (const listener of [...listeners])
+            listener();
+    };
+    const emit = () => {
+        snapshot = [...records.values()];
+        if (typeof requestAnimationFrame !== "function") {
+            for (const listener of [...listeners])
+                listener();
+            return;
+        }
+        if (frame !== 0)
+            return;
+        frame = requestAnimationFrame(flush);
+    };
+    return {
+        set(region) {
+            const prev = records.get(region.id);
+            if (prev !== undefined && sameRegion(prev, region))
+                return;
+            records.set(region.id, region);
+            emit();
+        },
+        remove(id) {
+            if (records.delete(id))
+                emit();
+        },
+        list: () => snapshot,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}
+const RegionRegistryContext = createContext(null);
+const GameLayoutContext = createContext(null);
+const SERVER_METRICS = {
+    layout: { left: 0, top: 0, right: 0, bottom: 0 },
+    visual: { left: 0, top: 0, right: 0, bottom: 0 },
+};
+function readViewportMetrics() {
+    if (typeof window === "undefined")
+        return SERVER_METRICS;
+    const layoutWidth = window.innerWidth;
+    const layoutHeight = window.innerHeight;
+    const vv = window.visualViewport;
+    const visual = vv
+        ? {
+            left: vv.offsetLeft,
+            top: vv.offsetTop,
+            right: vv.offsetLeft + vv.width,
+            bottom: vv.offsetTop + vv.height,
+        }
+        : { left: 0, top: 0, right: layoutWidth, bottom: layoutHeight };
+    return { layout: { left: 0, top: 0, right: layoutWidth, bottom: layoutHeight }, visual };
+}
+let cachedMetrics = SERVER_METRICS;
+function metricsSnapshot() {
+    const next = readViewportMetrics();
+    if (!sameRect(next.layout, cachedMetrics.layout) || !sameRect(next.visual, cachedMetrics.visual)) {
+        cachedMetrics = next;
+    }
+    return cachedMetrics;
+}
+function subscribeViewport(onChange) {
+    if (typeof window === "undefined")
+        return () => undefined;
+    window.addEventListener("resize", onChange);
+    window.addEventListener("orientationchange", onChange);
+    const vv = window.visualViewport;
+    vv?.addEventListener("resize", onChange);
+    vv?.addEventListener("scroll", onChange);
+    return () => {
+        window.removeEventListener("resize", onChange);
+        window.removeEventListener("orientationchange", onChange);
+        vv?.removeEventListener("resize", onChange);
+        vv?.removeEventListener("scroll", onChange);
+    };
+}
+/** Live visible viewport, tracking `window.visualViewport` (mobile browser chrome, pinch-zoom) with a layout-viewport fallback. */
+export function useViewportMetrics() {
+    return useSyncExternalStore(subscribeViewport, metricsSnapshot, () => SERVER_METRICS);
+}
+function measureSafeArea(probe) {
+    if (probe === null || typeof getComputedStyle !== "function")
+        return { top: 0, right: 0, bottom: 0, left: 0 };
+    const style = getComputedStyle(probe);
+    const px = (value) => {
+        const n = Number.parseFloat(value);
+        return Number.isFinite(n) ? n : 0;
+    };
+    return {
+        top: px(style.paddingTop),
+        right: px(style.paddingRight),
+        bottom: px(style.paddingBottom),
+        left: px(style.paddingLeft),
+    };
+}
+const SAFE_AREA_PROBE_STYLE = {
+    position: "fixed",
+    top: 0,
+    left: 0,
+    width: 0,
+    height: 0,
+    visibility: "hidden",
+    pointerEvents: "none",
+    paddingTop: "env(safe-area-inset-top, 0px)",
+    paddingRight: "env(safe-area-inset-right, 0px)",
+    paddingBottom: "env(safe-area-inset-bottom, 0px)",
+    paddingLeft: "env(safe-area-inset-left, 0px)",
+};
+/**
+ * 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 function GameViewportProvider({ platforms, className, style, children, }) {
+    const registry = useMemo(createRegionRegistry, []);
+    const metrics = useViewportMetrics();
+    const { coarsePointer } = useDisplayProfile();
+    const probeRef = useRef(null);
+    const [safeArea, setSafeArea] = useState({ top: 0, right: 0, bottom: 0, left: 0 });
+    const rootRef = useRef(null);
+    useEffect(() => {
+        const update = () => {
+            const next = measureSafeArea(probeRef.current);
+            setSafeArea((prev) => prev.top === next.top && prev.right === next.right && prev.bottom === next.bottom && prev.left === next.left
+                ? prev
+                : next);
+        };
+        update();
+        if (typeof window === "undefined")
+            return;
+        window.addEventListener("resize", update);
+        window.addEventListener("orientationchange", update);
+        return () => {
+            window.removeEventListener("resize", update);
+            window.removeEventListener("orientationchange", update);
+        };
+    }, [metrics]);
+    const regions = useSyncExternalStore(registry.subscribe, registry.list, () => EMPTY_REGIONS);
+    const mobileSupported = platforms?.includes("mobile") ?? true;
+    const visual = metrics.visual;
+    const vw = Math.max(0, visual.right - visual.left);
+    const vh = Math.max(0, visual.bottom - visual.top);
+    const layout = useMemo(() => {
+        const orientation = vw > 0 || vh > 0 ? orientationOf(vw, vh) : orientationOf(metrics.layout.right, metrics.layout.bottom);
+        const mode = resolveLayoutMode({
+            width: vw > 0 ? vw : metrics.layout.right,
+            height: vh > 0 ? vh : metrics.layout.bottom,
+            coarsePointer,
+            mobileSupported,
+        });
+        const reserved = regions
+            .filter((region) => region.kind === "control" || region.kind === "system")
+            .map((region) => region.rect);
+        const gameplayRect = computeGameplayRect(metrics.layout, safeArea, reserved);
+        return {
+            viewport: metrics.layout,
+            visualViewport: visual,
+            safeArea,
+            mode,
+            orientation,
+            regions,
+            controlZones: reserved,
+            gameplayRect,
+        };
+    }, [regions, metrics.layout, visual, vw, vh, coarsePointer, mobileSupported, safeArea]);
+    const collisions = useMemo(() => detectLayoutCollisions(regions), [regions]);
+    const forbidden = useMemo(() => collisions.filter((c) => c.severity === "forbid"), [collisions]);
+    useEffect(() => {
+        const root = rootRef.current;
+        if (root === null)
+            return;
+        if (forbidden.length === 0) {
+            root.removeAttribute("data-jg-layout-collision");
+            return;
+        }
+        const report = JSON.stringify(forbidden);
+        root.setAttribute("data-jg-layout-collision", report);
+        console.warn(`[jgengine] ${formatLayoutCollisions(forbidden)}\n  mode=${layout.mode} viewport=${Math.round(vw)}x${Math.round(vh)} safe=${safeArea.top}/${safeArea.right}/${safeArea.bottom}/${safeArea.left}`);
+    }, [forbidden, layout.mode, vw, vh, safeArea]);
+    useEffect(() => {
+        const ids = new Set();
+        for (const collision of forbidden) {
+            ids.add(collision.a);
+            ids.add(collision.b);
+        }
+        const marked = [];
+        for (const region of regions) {
+            if (region.element != null && ids.has(region.id)) {
+                region.element.setAttribute("data-jg-collision", "");
+                marked.push(region.element);
+            }
+        }
+        return () => {
+            for (const element of marked)
+                element.removeAttribute("data-jg-collision");
+        };
+    }, [forbidden, regions]);
+    const rootStyle = {
+        position: "relative",
+        width: "100%",
+        height: "100%",
+        "--jg-viewport-width": `${metrics.layout.right}px`,
+        "--jg-viewport-height": `${metrics.layout.bottom}px`,
+        "--jg-visual-viewport-width": `${Math.round(vw)}px`,
+        "--jg-visual-viewport-height": `${Math.round(vh)}px`,
+        "--jg-visual-viewport-offset-top": `${Math.round(visual.top)}px`,
+        "--jg-visual-viewport-offset-left": `${Math.round(visual.left)}px`,
+        "--jg-safe-top": `${safeArea.top}px`,
+        "--jg-safe-right": `${safeArea.right}px`,
+        "--jg-safe-bottom": `${safeArea.bottom}px`,
+        "--jg-safe-left": `${safeArea.left}px`,
+        ...style,
+    };
+    return (_jsx(RegionRegistryContext.Provider, { value: registry, children: _jsx(GameLayoutContext.Provider, { value: layout, children: _jsxs("div", { ref: rootRef, "data-jg-viewport": "", "data-jg-layout-mode": layout.mode, "data-jg-orientation": layout.orientation, className: className, style: rootStyle, children: [_jsx("div", { ref: probeRef, "aria-hidden": true, style: SAFE_AREA_PROBE_STYLE }), children] }) }) }));
+}
+/** The live shared viewport layout. Returns a neutral default outside a `GameViewportProvider` so it never throws in previews. */
+export function useGameViewportLayout() {
+    const layout = useContext(GameLayoutContext);
+    const metrics = useViewportMetrics();
+    return (layout ?? {
+        viewport: metrics.layout,
+        visualViewport: metrics.visual,
+        safeArea: { top: 0, right: 0, bottom: 0, left: 0 },
+        mode: resolveLayoutMode({ width: metrics.layout.right, height: metrics.layout.bottom, coarsePointer: false }),
+        orientation: orientationOf(metrics.layout.right, metrics.layout.bottom),
+        regions: [],
+        controlZones: [],
+        gameplayRect: metrics.layout,
+    });
+}
+/** The resolved explicit composition mode (`desktop-wide` … `mobile-portrait`). */
+export function useGameLayoutMode() {
+    return useGameViewportLayout().mode;
+}
+/** The live device orientation. */
+export function useGameOrientation() {
+    return useGameViewportLayout().orientation;
+}
+/** Rectangles reserved by touch controls and system UI — HUD placement should avoid these. */
+export function useReservedControlZones() {
+    return useGameViewportLayout().controlZones;
+}
+/** Live forbidden/warned region collisions (empty outside a provider). */
+export function useLayoutCollisions() {
+    const layout = useContext(GameLayoutContext);
+    return useMemo(() => (layout === null ? [] : detectLayoutCollisions(layout.regions)), [layout]);
+}
+function specKey(spec) {
+    return [
+        spec.id,
+        spec.kind,
+        spec.collisionPolicy,
+        spec.priority ?? "",
+        spec.collisionGroup ?? "",
+        (spec.allowOverlapWith ?? []).join("+"),
+    ].join("|");
+}
+/**
+ * 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 function useRegisterLayoutRegion(spec, ref, enabled = true) {
+    const registry = useContext(RegionRegistryContext);
+    const specRef = useRef(spec);
+    specRef.current = spec;
+    const key = specKey(spec);
+    useEffect(() => {
+        const element = ref.current;
+        if (registry === null || element === null || !enabled) {
+            registry?.remove(specRef.current.id);
+            return;
+        }
+        const measure = () => {
+            const rect = element.getBoundingClientRect();
+            registry.set({
+                ...specRef.current,
+                element,
+                rect: { left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom },
+            });
+        };
+        measure();
+        const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(measure);
+        observer?.observe(element);
+        if (typeof window !== "undefined") {
+            window.addEventListener("resize", measure);
+            window.addEventListener("orientationchange", measure);
+            window.visualViewport?.addEventListener("resize", measure);
+            window.visualViewport?.addEventListener("scroll", measure);
+        }
+        return () => {
+            observer?.disconnect();
+            if (typeof window !== "undefined") {
+                window.removeEventListener("resize", measure);
+                window.removeEventListener("orientationchange", measure);
+                window.visualViewport?.removeEventListener("resize", measure);
+                window.visualViewport?.removeEventListener("scroll", measure);
+            }
+            registry.remove(specRef.current.id);
+        };
+    }, [registry, ref, key, enabled]);
+}

package/dist/hooks.d.ts

@@ -32,6 +32,8 @@ export declare function useGamePhase(): {
     phase: GamePhase;
     setPhase: (phase: GamePhase) => void;
 };
+/** Live run phase that degrades to `"playing"` when rendered outside a `GameProvider` (component showcases, previews), so phase-gated chrome never throws. */
+export declare function useOptionalGamePhase(): GamePhase;
 export declare function useSceneEntities(): readonly SceneEntity[];
 export declare function useSceneObjects(): readonly SceneObject[];
 export declare function useWorldItems(): readonly WorldItemRecord[];

package/dist/hooks.js

@@ -3,7 +3,8 @@ 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";
+import { useGameContext, useOptionalGameContext } from "./provider.js";
+const noopSubscribe = () => () => undefined;
 import { createSelectCache, readSelectSnapshot } from "./selectSnapshot.js";
 export function useGameStore(selector, isEqual = Object.is) {
     const ctx = useGameContext();
@@ -30,6 +31,12 @@ export function useGamePhase() {
     const setPhase = useCallback((next) => setGamePhase(ctx, next), [ctx]);
     return { phase, setPhase };
 }
+/** Live run phase that degrades to `"playing"` when rendered outside a `GameProvider` (component showcases, previews), so phase-gated chrome never throws. */
+export function useOptionalGamePhase() {
+    const ctx = useOptionalGameContext();
+    const getSnapshot = useCallback(() => (ctx === null ? "playing" : gamePhase(ctx)), [ctx]);
+    return useSyncExternalStore(ctx?.subscribe ?? noopSubscribe, getSnapshot, getSnapshot);
+}
 export function useSceneEntities() {
     return useGameStore((ctx) => ctx.scene.entity.list());
 }
@@ -67,27 +74,34 @@ export function useFeed({ action, limit }) {
 export function useQuestJournal() {
     return useGameStore((ctx) => ctx.game.quest.list(ctx.player.userId));
 }
+const EMPTY_FRIENDS = [];
+const EMPTY_PARTY = [];
+const EMPTY_WORLD_INVITES = [];
+const EMPTY_CHAT = [];
+const EMPTY_FRIEND_REQUESTS = [];
+const EMPTY_PARTY_INVITES = [];
+const OFFLINE_PRESENCE = { online: false };
 export function useFriends() {
-    return useGameStore((ctx) => ctx.game.social.friends.list(ctx.player.userId));
+    return useGameStore((ctx) => ctx.game.social?.friends.list(ctx.player.userId) ?? EMPTY_FRIENDS);
 }
 export function useParty() {
-    return useGameStore((ctx) => ctx.game.social.party.list(ctx.player.userId));
+    return useGameStore((ctx) => ctx.game.social?.party.list(ctx.player.userId) ?? EMPTY_PARTY);
 }
 export function usePresence(userId) {
-    return useGameStore((ctx) => ctx.game.social.presence.get(userId));
+    return useGameStore((ctx) => ctx.game.social?.presence.get(userId) ?? OFFLINE_PRESENCE);
 }
 export function useWorldInvites() {
-    return useGameStore((ctx) => ctx.game.social.worldInvites.listFor(ctx.player.userId));
+    return useGameStore((ctx) => ctx.game.social?.worldInvites.listFor(ctx.player.userId) ?? EMPTY_WORLD_INVITES);
 }
 export function useChat(channelId, options) {
     const limit = options?.limit ?? 50;
-    return useGameStore((ctx) => ctx.game.chat.history(channelId, { limit, viewerUserId: ctx.player.userId }));
+    return useGameStore((ctx) => ctx.game.chat?.history(channelId, { limit, viewerUserId: ctx.player.userId }) ?? EMPTY_CHAT);
 }
 export function useFriendRequests() {
-    return useGameStore((ctx) => ctx.game.social.friends.requestsFor(ctx.player.userId));
+    return useGameStore((ctx) => ctx.game.social?.friends.requestsFor(ctx.player.userId) ?? EMPTY_FRIEND_REQUESTS);
 }
 export function usePartyInvites() {
-    return useGameStore((ctx) => ctx.game.social.party.invitesFor(ctx.player.userId));
+    return useGameStore((ctx) => ctx.game.social?.party.invitesFor(ctx.player.userId) ?? EMPTY_PARTY_INVITES);
 }
 /**
  * Polls a host-supplied session fetcher (e.g. createWsBackend().browse) and
@@ -134,11 +148,13 @@ export function useWorldBrowser(options) {
     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));
+    return useGameStore((ctx) => ctx.game.roster?.list(userId ?? ctx.player.userId) ?? EMPTY_ROSTER);
 }
+const EMPTY_ROSTER = [];
 export function useLeaderboard(stat, options) {
-    return useGameStore((ctx) => ctx.game.leaderboard.getTop(stat, options));
+    return useGameStore((ctx) => ctx.game.leaderboard?.getTop(stat, options) ?? EMPTY_LEADERBOARD);
 }
+const EMPTY_LEADERBOARD = [];
 export function useLocalPlayerDead(healthStatId = "health") {
     return useGameStore((ctx) => {
         const player = localPlayerEntity(ctx);