@jgengine/shell 0.10.0 → 0.11.0

package/dist/touch/TouchControlsOverlay.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo, useRef } from "react";
+import { useMemo, useRef, useState, } from "react";
 import { createGestureSurfaceTracker } from "@jgengine/core/input/gestureSurface";
 import { createTouchGestureTracker } from "@jgengine/core/input/touchGestures";
-import { touchCode } from "@jgengine/core/input/touchScheme";
+import { touchCode, } from "@jgengine/core/input/touchScheme";
 import { GameIcon, iconForAction, isGameIconName } from "@jgengine/react/gameIcons";
 import { useRegisterLayoutRegion } from "@jgengine/react/gameViewport";
 const MOVEMENT_ZONE = { id: "control:movement", kind: "control", collisionPolicy: "forbid", collisionGroup: "touch-dock" };
@@ -14,6 +14,7 @@ const JOYSTICK_DEADZONE = 0.28;
 const JOYSTICK_AXIS_THRESHOLD = 0.42;
 const LOOK_TAP_TUNING = { tapMoveThresholdPx: 12, tapMaxMs: 280, longPressMs: 450 };
 const BUTTON_SIZE = 56;
+const RAIL_BUTTON_SIZE = 64;
 const RING1_RADIUS = 112;
 const RING2_RADIUS = 178;
 const RING1_CAPACITY = 3;
@@ -21,6 +22,74 @@ const RING2_CAPACITY = 5;
 const RING1_ANGLES = [[], [40], [16, 64], [12, 44, 76]];
 const DOCK_BASE_PADDING = 20;
 const UTILITY_ROW_HEIGHT = 28;
+/** width:height footprint of each silhouette; the longer side equals the button size. */
+const SHAPE_ASPECT = {
+    circle: { w: 1, h: 1 },
+    square: { w: 1, h: 1 },
+    wheel: { w: 1, h: 1 },
+    pedal: { w: 0.78, h: 1 },
+    lever: { w: 0.64, h: 1 },
+    trigger: { w: 0.92, h: 1 },
+    tab: { w: 1.5, h: 0.72 },
+};
+const STYLE_TOKENS = {
+    glass: {
+        restFill: "rgba(255,255,255,0.10)",
+        restStroke: "rgba(255,255,255,0.28)",
+        strokeWidth: 2,
+        activeFill: "rgba(255,255,255,0.34)",
+        activeStroke: "rgba(255,255,255,0.7)",
+        text: "rgba(255,255,255,0.92)",
+        wrapper: "drop-shadow-[0_1px_3px_rgba(0,0,0,0.35)]",
+        activeWrapper: "drop-shadow-[0_1px_5px_rgba(0,0,0,0.4)]",
+        joyBase: { border: "1px solid rgba(255,255,255,0.2)", background: "rgba(255,255,255,0.1)", backdropFilter: "blur(4px)" },
+        joyThumb: { border: "1px solid rgba(255,255,255,0.3)", background: "rgba(255,255,255,0.25)" },
+        chipRest: { border: "1px solid rgba(255,255,255,0.2)", background: "rgba(0,0,0,0.4)", color: "rgba(255,255,255,0.8)", backdropFilter: "blur(4px)" },
+        chipActive: { border: "1px solid rgba(255,255,255,0.5)", background: "rgba(255,255,255,0.25)", color: "#fff" },
+    },
+    arcade: {
+        restFill: "rgba(9,12,20,0.82)",
+        restStroke: "rgba(120,224,255,0.75)",
+        strokeWidth: 3,
+        activeFill: "rgba(120,224,255,0.9)",
+        activeStroke: "rgba(240,255,255,0.95)",
+        text: "rgba(190,244,255,0.95)",
+        wrapper: "drop-shadow-[0_0_9px_rgba(80,200,255,0.5)]",
+        activeWrapper: "drop-shadow-[0_0_16px_rgba(120,224,255,0.85)]",
+        joyBase: { border: "3px solid rgba(120,224,255,0.7)", background: "rgba(9,12,20,0.8)", boxShadow: "0 0 16px rgba(80,200,255,0.4)" },
+        joyThumb: { border: "2px solid rgba(240,255,255,0.9)", background: "rgba(120,224,255,0.85)" },
+        chipRest: { border: "2px solid rgba(120,224,255,0.6)", background: "rgba(9,12,20,0.85)", color: "rgba(190,244,255,0.95)", fontWeight: 700 },
+        chipActive: { border: "2px solid rgba(240,255,255,0.95)", background: "rgba(120,224,255,0.9)", color: "#04121a", fontWeight: 700 },
+    },
+    mechanical: {
+        restFill: "rgba(63,68,78,0.9)",
+        restStroke: "rgba(210,214,222,0.4)",
+        strokeWidth: 2.5,
+        activeFill: "rgba(120,126,138,0.95)",
+        activeStroke: "rgba(240,242,246,0.7)",
+        text: "rgba(232,234,240,0.95)",
+        wrapper: "drop-shadow-[0_2px_4px_rgba(0,0,0,0.55)]",
+        activeWrapper: "drop-shadow-[0_1px_2px_rgba(0,0,0,0.7)]",
+        joyBase: { border: "2px solid rgba(210,214,222,0.35)", background: "linear-gradient(180deg,rgba(78,84,94,0.92),rgba(44,48,56,0.92))", boxShadow: "0 3px 8px rgba(0,0,0,0.5)" },
+        joyThumb: { border: "2px solid rgba(240,242,246,0.5)", background: "linear-gradient(180deg,rgba(150,156,166,0.95),rgba(96,102,112,0.95))" },
+        chipRest: { border: "1px solid rgba(210,214,222,0.35)", background: "linear-gradient(180deg,rgba(72,78,88,0.92),rgba(40,44,52,0.92))", color: "rgba(232,234,240,0.95)" },
+        chipActive: { border: "1px solid rgba(240,242,246,0.6)", background: "rgba(120,126,138,0.95)", color: "#fff" },
+    },
+    minimal: {
+        restFill: "rgba(0,0,0,0.001)",
+        restStroke: "rgba(255,255,255,0.45)",
+        strokeWidth: 1.75,
+        activeFill: "rgba(255,255,255,0.14)",
+        activeStroke: "rgba(255,255,255,0.85)",
+        text: "rgba(255,255,255,0.85)",
+        wrapper: "",
+        activeWrapper: "",
+        joyBase: { border: "1.5px solid rgba(255,255,255,0.4)", background: "transparent" },
+        joyThumb: { border: "1.5px solid rgba(255,255,255,0.6)", background: "rgba(255,255,255,0.1)" },
+        chipRest: { border: "1px solid rgba(255,255,255,0.35)", background: "transparent", color: "rgba(255,255,255,0.8)" },
+        chipActive: { border: "1px solid rgba(255,255,255,0.8)", background: "rgba(255,255,255,0.14)", color: "#fff" },
+    },
+};
 function polar(radius, deg, buttonSize) {
     const rad = (deg * Math.PI) / 180;
     return {
@@ -63,23 +132,38 @@ function primaryClusterExtent(count, scale = 1) {
         return (RING2_RADIUS + BUTTON_SIZE / 2) * scale;
     return Math.ceil(count / 4) * (BUTTON_SIZE + 12) * scale;
 }
+const BOTTOM_ANCHORS = new Set(["bottom-left", "bottom-center", "bottom-right"]);
+const ARC_ANCHORS = new Set(["bottom-left", "bottom-right"]);
 /**
- * Vertical space (px, excluding device safe areas) the dock occupies above
- * the bottom edge. The shell publishes it as `--jg-hud-dock-clearance` so
- * `HudCanvas` regions never collide with touch controls.
+ * Vertical space (px, excluding device safe areas) that *bottom-docked* clusters
+ * occupy above the bottom edge. The shell publishes it as
+ * `--jg-hud-dock-clearance` so `HudCanvas` regions never collide with touch
+ * controls. Side rails and top clusters reserve their own rectangles through the
+ * layout registry instead of this scalar.
  */
 export function touchDockClearance(scheme, scale = 1) {
     if (scheme === null)
         return 0;
+    const layout = scheme.layout;
     let primary = 0;
     let utility = 0;
     for (const button of scheme.buttons) {
+        if (button.anchor !== null)
+            continue;
         if (button.kind === "utility")
             utility += 1;
         else
             primary += 1;
     }
-    const tallest = Math.max(scheme.joystick !== null ? JOYSTICK_SIZE * scale : 0, primaryClusterExtent(primary, scale), utility > 0 ? UTILITY_ROW_HEIGHT : 0);
+    const heights = [];
+    if (scheme.joystick !== null && BOTTOM_ANCHORS.has(layout.movement))
+        heights.push(JOYSTICK_SIZE * scale);
+    if (primary > 0 && BOTTOM_ANCHORS.has(layout.actions)) {
+        heights.push(ARC_ANCHORS.has(layout.actions) ? primaryClusterExtent(primary, scale) : RAIL_BUTTON_SIZE * scale + 12);
+    }
+    if (utility > 0 && BOTTOM_ANCHORS.has(layout.utility))
+        heights.push(UTILITY_ROW_HEIGHT);
+    const tallest = heights.length === 0 ? 0 : Math.max(...heights);
     if (tallest === 0)
         return 0;
     return tallest + DOCK_BASE_PADDING + 12;
@@ -158,7 +242,7 @@ function joystickDirections(joystick, nx, ny) {
         active.add(joystick.right);
     return active;
 }
-function VirtualJoystick({ joystick, sink, scale = 1 }) {
+function VirtualJoystick({ joystick, sink, tokens, scale = 1, }) {
     const baseRef = useRef(null);
     const thumbRef = useRef(null);
     const pointerIdRef = useRef(null);
@@ -200,7 +284,7 @@ function VirtualJoystick({ joystick, sink, scale = 1 }) {
         if (thumbRef.current !== null)
             thumbRef.current.style.transform = "translate(0px, 0px)";
     };
-    return (_jsx("div", { ref: baseRef, className: "pointer-events-auto relative flex touch-none select-none items-center justify-center rounded-full border border-white/20 bg-white/10 backdrop-blur-sm", style: { width: size, height: size }, onPointerDown: (event) => {
+    return (_jsx("div", { ref: baseRef, className: "pointer-events-auto relative flex touch-none select-none items-center justify-center rounded-full", style: { width: size, height: size, ...tokens.joyBase }, onPointerDown: (event) => {
             if (pointerIdRef.current !== null)
                 return;
             pointerIdRef.current = event.pointerId;
@@ -216,7 +300,7 @@ function VirtualJoystick({ joystick, sink, scale = 1 }) {
                 return;
             event.stopPropagation();
             releaseAll();
-        }, onPointerCancel: () => releaseAll(), children: _jsx("div", { ref: thumbRef, className: "rounded-full border border-white/30 bg-white/25", style: { width: thumbSize, height: thumbSize } }) }));
+        }, onPointerCancel: () => releaseAll(), children: _jsx("div", { ref: thumbRef, className: "rounded-full", style: { width: thumbSize, height: thumbSize, ...tokens.joyThumb } }) }));
 }
 function touchButtonIcon(button) {
     if (button.icon === false)
@@ -225,65 +309,160 @@ function touchButtonIcon(button) {
         return button.icon;
     return iconForAction(button.action);
 }
-function TouchActionButton({ button, sink, scale = 1 }) {
+function ShapeSilhouette({ shape, width, height, fill, stroke, strokeWidth, }) {
+    const common = { fill, stroke, strokeWidth, strokeLinejoin: "round", strokeLinecap: "round" };
+    const body = (() => {
+        switch (shape) {
+            case "circle":
+                return _jsx("circle", { cx: 50, cy: 50, r: 46, ...common });
+            case "square":
+                return _jsx("rect", { x: 7, y: 7, width: 86, height: 86, rx: 20, ...common });
+            case "wheel":
+                return (_jsxs("g", { ...common, children: [_jsx("circle", { cx: 50, cy: 50, r: 44, fill: fill }), _jsx("circle", { cx: 50, cy: 50, r: 16, fill: "none" }), _jsx("path", { d: "M50 34 V18 M36 58 L22 72 M64 58 L78 72", fill: "none" })] }));
+            case "pedal":
+                return (_jsxs("g", { ...common, children: [_jsx("path", { d: "M30 6 h40 a10 10 0 0 1 10 10 v58 a16 16 0 0 1 -16 16 h-38 a16 16 0 0 1 -16 -16 v-58 a10 10 0 0 1 10 -10 Z" }), _jsx("path", { d: "M26 26 h48 M26 42 h48 M26 58 h48", fill: "none", strokeWidth: strokeWidth * 0.8 })] }));
+            case "lever":
+                return (_jsxs("g", { ...common, children: [_jsx("circle", { cx: 50, cy: 22, r: 18 }), _jsx("path", { d: "M42 36 h16 v52 a8 8 0 0 1 -16 0 Z" })] }));
+            case "trigger":
+                return _jsx("path", { d: "M18 20 h44 a24 24 0 0 1 24 24 v10 a30 30 0 0 1 -30 30 h-24 a14 14 0 0 1 -14 -14 v-40 a10 10 0 0 1 0 -10 Z", ...common });
+            case "tab":
+                return _jsx("path", { d: "M6 18 a12 12 0 0 1 12 -12 h124 a12 12 0 0 1 12 12 v20 a12 12 0 0 1 -12 12 h-124 a12 12 0 0 1 -12 -12 Z", ...common });
+        }
+    })();
+    const viewBox = shape === "tab" ? "0 0 160 56" : "0 0 100 100";
+    return (_jsx("svg", { width: width, height: height, viewBox: viewBox, className: "pointer-events-none absolute inset-0", children: body }));
+}
+function TouchActionButton({ button, sink, tokens, size, fit, }) {
     const pointerIdRef = useRef(null);
+    const [pressed, setPressed] = useState(false);
     const icon = touchButtonIcon(button);
-    const size = BUTTON_SIZE * scale;
+    const aspect = SHAPE_ASPECT[button.shape];
+    const svgW = size * aspect.w;
+    const svgH = size * aspect.h;
+    const boxW = fit === "box" ? size : svgW;
+    const boxH = fit === "box" ? size : svgH;
+    const iconSize = Math.round(Math.min(svgW, svgH) * 0.46);
     const releaseIfHeld = () => {
         if (pointerIdRef.current === null)
             return;
         pointerIdRef.current = null;
+        setPressed(false);
         sink.onCodeUp(touchCode(button.action));
     };
-    return (_jsx("button", { type: "button", "aria-label": button.label, style: { width: size, height: size }, className: "pointer-events-auto flex touch-none select-none items-center justify-center rounded-full border border-white/25 bg-white/10 text-center text-[10px] font-semibold uppercase leading-tight tracking-wide text-white/90 backdrop-blur-sm active:border-white/50 active:bg-white/30", onPointerDown: (event) => {
+    return (_jsx("button", { type: "button", "aria-label": button.label, "data-touch-shape": button.shape, style: { width: boxW, height: boxH, transform: pressed ? "scale(0.93)" : "scale(1)", transition: "transform 90ms" }, className: `pointer-events-auto relative flex touch-none select-none items-center justify-center ${pressed ? tokens.activeWrapper : tokens.wrapper}`, onPointerDown: (event) => {
             if (pointerIdRef.current !== null)
                 return;
             pointerIdRef.current = event.pointerId;
             event.currentTarget.setPointerCapture(event.pointerId);
+            setPressed(true);
             sink.onCodeDown(touchCode(button.action));
         }, onPointerUp: (event) => {
             event.stopPropagation();
             releaseIfHeld();
-        }, onPointerCancel: () => releaseIfHeld(), onContextMenu: (event) => event.preventDefault(), children: icon !== null ? _jsx(GameIcon, { name: icon, size: Math.round(26 * scale) }) : _jsx("span", { className: "px-1", children: button.label }) }));
+        }, onPointerCancel: () => releaseIfHeld(), onContextMenu: (event) => event.preventDefault(), children: _jsxs("div", { className: "relative", style: { width: svgW, height: svgH }, children: [button.image !== null ? (_jsx("img", { src: button.image, alt: "", draggable: false, className: "pointer-events-none absolute inset-0 h-full w-full select-none object-contain", style: { filter: pressed ? "brightness(1.25)" : undefined } })) : (_jsx(ShapeSilhouette, { shape: button.shape, width: svgW, height: svgH, fill: pressed ? tokens.activeFill : tokens.restFill, stroke: pressed ? tokens.activeStroke : tokens.restStroke, strokeWidth: tokens.strokeWidth })), _jsx("span", { className: "absolute inset-0 flex items-center justify-center text-center text-[10px] font-semibold uppercase leading-tight tracking-wide", style: { color: tokens.text }, children: icon !== null ? _jsx(GameIcon, { name: icon, size: iconSize }) : _jsx("span", { className: "px-1", children: button.label }) })] }) }));
 }
-function TouchUtilityChip({ button, sink }) {
+function TouchUtilityChip({ button, sink, tokens }) {
     const pointerIdRef = useRef(null);
+    const [pressed, setPressed] = useState(false);
     const releaseIfHeld = () => {
         if (pointerIdRef.current === null)
             return;
         pointerIdRef.current = null;
+        setPressed(false);
         sink.onCodeUp(touchCode(button.action));
     };
-    return (_jsx("button", { type: "button", "aria-label": button.label, className: "pointer-events-auto flex h-7 touch-none select-none items-center rounded-full border border-white/20 bg-black/40 px-3 text-[10px] font-semibold uppercase tracking-wide text-white/80 backdrop-blur-sm active:border-white/50 active:bg-white/25", onPointerDown: (event) => {
+    return (_jsx("button", { type: "button", "aria-label": button.label, style: pressed ? tokens.chipActive : tokens.chipRest, className: "pointer-events-auto flex h-7 touch-none select-none items-center rounded-full px-3 text-[10px] font-semibold uppercase tracking-wide", onPointerDown: (event) => {
             if (pointerIdRef.current !== null)
                 return;
             pointerIdRef.current = event.pointerId;
             event.currentTarget.setPointerCapture(event.pointerId);
+            setPressed(true);
             sink.onCodeDown(touchCode(button.action));
         }, onPointerUp: (event) => {
             event.stopPropagation();
             releaseIfHeld();
         }, onPointerCancel: () => releaseIfHeld(), onContextMenu: (event) => event.preventDefault(), children: button.label }));
 }
-function PrimaryButtonCluster({ buttons, sink, scale = 1 }) {
+function ThumbArcCluster({ buttons, sink, tokens, scale = 1, }) {
     const offsets = primaryButtonOffsets(buttons.length, scale);
     if (offsets === null) {
-        return (_jsx("div", { className: "flex max-w-[60%] flex-wrap items-end justify-end gap-3", children: buttons.map((button) => (_jsx(TouchActionButton, { button: button, sink: sink, scale: scale }, button.action))) }));
+        return (_jsx("div", { className: "flex max-w-[60%] flex-wrap items-end justify-end gap-3", children: buttons.map((button) => (_jsx(TouchActionButton, { button: button, sink: sink, tokens: tokens, size: BUTTON_SIZE * scale, fit: "box" }, button.action))) }));
     }
     const extent = primaryClusterExtent(buttons.length, scale);
     return (_jsx("div", { className: "pointer-events-none relative", style: { width: extent, height: extent }, children: buttons.map((button, index) => {
             const offset = offsets[index];
-            return (_jsx("div", { className: "absolute", style: { right: offset?.right ?? 0, bottom: offset?.bottom ?? 0 }, children: _jsx(TouchActionButton, { button: button, sink: sink, scale: scale }) }, button.action));
+            return (_jsx("div", { className: "absolute", style: { right: offset?.right ?? 0, bottom: offset?.bottom ?? 0 }, children: _jsx(TouchActionButton, { button: button, sink: sink, tokens: tokens, size: BUTTON_SIZE * scale, fit: "box" }) }, button.action));
         }) }));
 }
-export function TouchControlsDock({ scheme, sink, scale = 1 }) {
-    const primary = scheme.buttons.filter((button) => button.kind !== "utility");
-    const utility = scheme.buttons.filter((button) => button.kind === "utility");
+/** Vertical rail (`left`/`right`) or a wrapping row for the remaining anchors. */
+function StackCluster({ buttons, utility, sink, tokens, column, scale = 1, }) {
+    return (_jsxs("div", { className: `flex ${column ? "flex-col" : "flex-row flex-wrap"} items-center justify-center gap-3`, children: [buttons.map((button) => (_jsx(TouchActionButton, { button: button, sink: sink, tokens: tokens, size: RAIL_BUTTON_SIZE * scale, fit: "natural" }, button.action))), utility.map((button) => (_jsx(TouchUtilityChip, { button: button, sink: sink, tokens: tokens }, button.action)))] }));
+}
+const ANCHOR_POSITION = {
+    "bottom-left": { bottom: 0, left: 0 },
+    "bottom-center": { bottom: 0, left: "50%", transform: "translateX(-50%)" },
+    "bottom-right": { bottom: 0, right: 0 },
+    left: { top: "50%", left: 0, transform: "translateY(-50%)" },
+    right: { top: "50%", right: 0, transform: "translateY(-50%)" },
+    "top-left": { top: 0, left: 0 },
+    "top-center": { top: 0, left: "50%", transform: "translateX(-50%)" },
+    "top-right": { top: 0, right: 0 },
+};
+function anchorInset(anchor) {
+    const safeBottom = "env(safe-area-inset-bottom, 0px)";
+    const safeTop = "env(safe-area-inset-top, 0px)";
+    const safeLeft = "env(safe-area-inset-left, 0px)";
+    const safeRight = "env(safe-area-inset-right, 0px)";
+    const pad = `${DOCK_BASE_PADDING}px`;
+    const style = {};
+    if (anchor.startsWith("bottom"))
+        style.paddingBottom = `calc(${safeBottom} + ${pad})`;
+    if (anchor.startsWith("top"))
+        style.paddingTop = `calc(${safeTop} + ${pad})`;
+    if (anchor === "left" || anchor.endsWith("left"))
+        style.paddingLeft = `calc(${safeLeft} + ${pad})`;
+    if (anchor === "right" || anchor.endsWith("right"))
+        style.paddingRight = `calc(${safeRight} + ${pad})`;
+    if (anchor === "bottom-center" || anchor === "top-center") {
+        style.paddingLeft = `calc(${safeLeft} + ${pad})`;
+        style.paddingRight = `calc(${safeRight} + ${pad})`;
+    }
+    return style;
+}
+function AnchoredSlot({ anchor, children, slotRef, }) {
+    return (_jsx("div", { className: "pointer-events-none absolute z-40", style: { ...ANCHOR_POSITION[anchor], ...anchorInset(anchor) }, children: _jsx("div", { ref: slotRef, children: children }) }));
+}
+function bucketByAnchor(buttons) {
+    const map = new Map();
+    for (const button of buttons) {
+        if (button.anchor === null)
+            continue;
+        const bucket = map.get(button.anchor) ?? { primary: [], utility: [] };
+        if (button.kind === "utility")
+            bucket.utility.push(button);
+        else
+            bucket.primary.push(button);
+        map.set(button.anchor, bucket);
+    }
+    return map;
+}
+export function TouchControlsDock({ scheme, sink, style, scale = 1, }) {
+    const tokens = STYLE_TOKENS[style ?? scheme.style];
+    const layout = scheme.layout;
+    const docked = scheme.buttons.filter((button) => button.anchor === null);
+    const primary = docked.filter((button) => button.kind !== "utility");
+    const utility = docked.filter((button) => button.kind === "utility");
+    const extras = useMemo(() => bucketByAnchor(scheme.buttons), [scheme.buttons]);
     const joystickRef = useRef(null);
     const actionsRef = useRef(null);
     const utilityRef = useRef(null);
     useRegisterLayoutRegion(MOVEMENT_ZONE, joystickRef, scheme.joystick !== null);
     useRegisterLayoutRegion(ACTIONS_ZONE, actionsRef, primary.length > 0);
     useRegisterLayoutRegion(UTILITY_ZONE, utilityRef, utility.length > 0);
-    return (_jsxs("div", { className: "pointer-events-none absolute inset-x-0 bottom-0 z-40", style: { paddingBottom: `calc(env(safe-area-inset-bottom, 0px) + ${DOCK_BASE_PADDING}px)` }, children: [_jsxs("div", { className: "flex items-end justify-between gap-4 px-5", children: [_jsx("div", { ref: joystickRef, children: scheme.joystick !== null ? _jsx(VirtualJoystick, { joystick: scheme.joystick, sink: sink, scale: scale }) : null }), _jsx("div", { ref: actionsRef, children: _jsx(PrimaryButtonCluster, { buttons: primary, sink: sink, scale: scale }) })] }), utility.length > 0 ? (_jsx("div", { className: "pointer-events-none absolute inset-x-0 flex justify-center", style: { bottom: "calc(env(safe-area-inset-bottom, 0px) + 8px)" }, children: _jsx("div", { ref: utilityRef, className: "flex gap-2", children: utility.map((button) => (_jsx(TouchUtilityChip, { button: button, sink: sink }, button.action))) }) })) : null] }));
+    const actionsColumn = layout.actions === "left" || layout.actions === "right";
+    const utilityColumn = layout.utility === "left" || layout.utility === "right";
+    return (_jsxs(ResolvedLayout, { children: [scheme.joystick !== null ? (_jsx(AnchoredSlot, { anchor: layout.movement, slotRef: joystickRef, children: _jsx(VirtualJoystick, { joystick: scheme.joystick, sink: sink, tokens: tokens, scale: scale }) })) : null, primary.length > 0 ? (_jsx(AnchoredSlot, { anchor: layout.actions, slotRef: actionsRef, children: ARC_ANCHORS.has(layout.actions) ? (_jsx(ThumbArcCluster, { buttons: primary, sink: sink, tokens: tokens, scale: scale })) : (_jsx(StackCluster, { buttons: primary, utility: [], sink: sink, tokens: tokens, column: actionsColumn, scale: scale })) })) : null, utility.length > 0 ? (_jsx(AnchoredSlot, { anchor: layout.utility, slotRef: utilityRef, children: _jsx(StackCluster, { buttons: [], utility: utility, sink: sink, tokens: tokens, column: utilityColumn, scale: scale }) })) : null, [...extras.entries()].map(([anchor, bucket]) => (_jsx(AnchoredSlot, { anchor: anchor, children: _jsx(StackCluster, { buttons: bucket.primary, utility: bucket.utility, sink: sink, tokens: tokens, column: anchor === "left" || anchor === "right", scale: scale }) }, anchor)))] }));
+}
+function ResolvedLayout({ children }) {
+    return _jsx("div", { className: "pointer-events-none absolute inset-0 z-40", children: children });
 }

package/dist/useShellMultiplayerSync.d.ts

@@ -0,0 +1,9 @@
+import { type Dispatch, type SetStateAction } from "react";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { PresencePoseRow } from "@jgengine/core/runtime/transport";
+import type { ShellMultiplayer } from "./multiplayer.js";
+import type { PlayableGame } from "./registry.js";
+/** Joins the multiplayer server for the live context and wires presence, feed relay, and chat sync until teardown. */
+export declare function useShellMultiplayerSync(ctx: GameContext | null, multiplayer: ShellMultiplayer | null, playable: PlayableGame, serverIdRef: {
+    current: string | null;
+}, setRemotePlayers: Dispatch<SetStateAction<PresencePoseRow[]>>): void;

package/dist/useShellMultiplayerSync.js

@@ -0,0 +1,98 @@
+import { useEffect } from "react";
+import { isServerAuthoritative } from "@jgengine/core/runtime/adapter";
+import { attachWorldSync } from "./worldSync.js";
+/** Joins the multiplayer server for the live context and wires presence, feed relay, and chat sync until teardown. */
+export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef, setRemotePlayers) {
+    useEffect(() => {
+        if (ctx === null || multiplayer === null)
+            return;
+        let disposed = false;
+        const cleanups = [];
+        void multiplayer.backend.transport
+            .joinServer({ gameId: multiplayer.gameId })
+            .then((joined) => {
+            if (disposed) {
+                void multiplayer.backend.transport.leaveServer({ serverId: joined.serverId });
+                return;
+            }
+            serverIdRef.current = joined.serverId;
+            if (isServerAuthoritative(playable.game.multiplayer) && multiplayer.backend.feeds !== undefined) {
+                cleanups.push(attachWorldSync(multiplayer.backend.feeds, joined.serverId, ctx));
+            }
+            cleanups.push(multiplayer.backend.presenceSync.subscribe(joined.serverId, (rows) => {
+                setRemotePlayers(rows.filter((row) => row.userId !== multiplayer.userId));
+            }));
+            const seen = new Set();
+            let injecting = false;
+            for (const action of multiplayer.feedActions) {
+                cleanups.push(ctx.game.feed.subscribe(action, (entry) => {
+                    if (injecting)
+                        return;
+                    void multiplayer.backend
+                        .pushFeedEntry({
+                        serverId: joined.serverId,
+                        action,
+                        entry: { at: entry.at, data: entry.data, from: multiplayer.userId },
+                    })
+                        .catch(() => undefined);
+                }));
+                const remoteUnsub = multiplayer.backend.feeds?.subscribeFeed({ serverId: joined.serverId, action }, (view) => {
+                    for (const raw of view.entries) {
+                        const remote = raw;
+                        if (typeof remote.from !== "string" || remote.from === multiplayer.userId)
+                            continue;
+                        const key = `${action}|${remote.from}|${remote.at ?? 0}`;
+                        if (seen.has(key))
+                            continue;
+                        seen.add(key);
+                        injecting = true;
+                        ctx.game.feed.push(action, remote.data);
+                        injecting = false;
+                    }
+                });
+                if (remoteUnsub !== undefined)
+                    cleanups.push(remoteUnsub);
+            }
+            const chatSync = multiplayer.backend.chatSyncFor?.(joined.serverId);
+            if (chatSync !== undefined && ctx.game.chat !== undefined) {
+                const chat = ctx.game.chat;
+                const globalChannelIds = new Set(chat
+                    .channels()
+                    .filter((channel) => channel.kind === "global")
+                    .map((channel) => channel.id));
+                const seenRemoteChat = new Set();
+                cleanups.push(ctx.game.events.subscribe("chat.message", (event) => {
+                    if (event.fromUserId !== multiplayer.userId)
+                        return;
+                    if (!globalChannelIds.has(event.channelId))
+                        return;
+                    void chatSync.send(event.channelId, event.body).catch(() => undefined);
+                }));
+                for (const channelId of globalChannelIds) {
+                    cleanups.push(chatSync.subscribe(channelId, (messages) => {
+                        for (const message of messages) {
+                            if (message.fromUserId === multiplayer.userId)
+                                continue;
+                            if (seenRemoteChat.has(message.id))
+                                continue;
+                            seenRemoteChat.add(message.id);
+                            chat.send(message.fromUserId, message.channelId, message.body);
+                        }
+                    }));
+                }
+            }
+        })
+            .catch(() => undefined);
+        return () => {
+            disposed = true;
+            for (const cleanup of cleanups)
+                cleanup();
+            const serverId = serverIdRef.current;
+            serverIdRef.current = null;
+            setRemotePlayers([]);
+            if (serverId !== null) {
+                void multiplayer.backend.transport.leaveServer({ serverId }).catch(() => undefined);
+            }
+        };
+    }, [ctx, multiplayer, playable]);
+}

package/dist/visibility/CullingProvider.js

@@ -4,7 +4,7 @@ import { useThree, useFrame } from "@react-three/fiber";
 import * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { createVisibilitySystem } from "@jgengine/core/visibility/visibilitySystem";
-import { CAMERA_POST_FRAME_PRIORITY } from "../camera/index.js";
+import { CAMERA_POST_FRAME_PRIORITY } from "../camera/cameraRigs.js";
 const ALWAYS_VISIBLE = () => true;
 const alwaysVisibleRef = { current: ALWAYS_VISIBLE };
 const CullingContext = createContext(null);

package/dist/water/OceanConfig.d.ts

@@ -96,7 +96,9 @@ export declare const OCEAN_QUALITY_PRESETS: Record<OceanQualityPreset, {
     resolution: number;
 }>;
 export declare const DEFAULT_OCEAN_CONFIG: ResolvedOceanConfig;
+/** @internal */
 export declare function createOceanConfig(patch?: OceanConfig): ResolvedOceanConfig;
+/** @internal */
 export declare function buildOceanWaveUniforms(config: ResolvedOceanConfig): {
     directions: THREE.Vector2[];
     params: THREE.Vector4[];

package/dist/water/OceanConfig.js

@@ -87,6 +87,7 @@ function resolveWave(wave, fallback, config, customWaves) {
         steepness: clamp(finiteOr(wave?.steepness, fallback.steepness) * config.steepness, 0, 1.2),
     };
 }
+/** @internal */
 export function createOceanConfig(patch = {}) {
     const quality = patch.quality ?? DEFAULT_OCEAN_CONFIG.quality;
     const preset = OCEAN_QUALITY_PRESETS[quality];
@@ -126,6 +127,7 @@ export function createOceanConfig(patch = {}) {
     const waves = Array.from({ length: MAX_OCEAN_WAVES }, (_, index) => resolveWave(inputWaves[index], defaultWaves[index], withoutWaves, customWaves));
     return { ...withoutWaves, waves };
 }
+/** @internal */
 export function buildOceanWaveUniforms(config) {
     const directions = [];
     const params = [];

package/dist/weather/fireSpreadPose.d.ts

@@ -1,2 +1,3 @@
 import type { Euler, Quaternion } from "three";
+/** @internal */
 export declare function setBillboardQuaternion(quaternion: Quaternion, euler: Euler, yaw: number): void;

package/dist/weather/fireSpreadPose.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function setBillboardQuaternion(quaternion, euler, yaw) {
     euler.set(0, yaw, 0);
     quaternion.setFromEuler(euler);

package/dist/weather/weatherGeometry.d.ts

@@ -1,2 +1,3 @@
 import * as THREE from "three";
+/** @internal */
 export declare function createWeatherQuadGeometry(maxCount: number, seed: number): THREE.InstancedBufferGeometry;

package/dist/weather/weatherGeometry.js

@@ -1,5 +1,6 @@
 import * as THREE from "three";
 import { createWeatherSeedAttributes } from "./weatherMath.js";
+/** @internal */
 export function createWeatherQuadGeometry(maxCount, seed) {
     const count = Math.max(0, Math.floor(maxCount));
     const geometry = new THREE.InstancedBufferGeometry();

package/dist/weather/weatherMath.d.ts

@@ -2,10 +2,13 @@ export declare const DEFAULT_RAIN_COUNT = 2000;
 export declare const DEFAULT_SNOW_COUNT = 1500;
 export declare const DEFAULT_RAIN_DENSITY = 0.45;
 export declare const DEFAULT_SNOW_DENSITY = 0.5;
+/** @internal */
 export declare function clampWeatherRatio(value: number): number;
+/** @internal */
 export declare function resolveWeatherInstanceCount(maxCount: number, density: number, budget?: number): number;
 export interface WeatherSeedAttributes {
     spawn: Float32Array;
     drift: Float32Array;
 }
+/** @internal */
 export declare function createWeatherSeedAttributes(maxCount: number, seed: number): WeatherSeedAttributes;

package/dist/weather/weatherMath.js

@@ -2,6 +2,7 @@ export const DEFAULT_RAIN_COUNT = 2000;
 export const DEFAULT_SNOW_COUNT = 1500;
 export const DEFAULT_RAIN_DENSITY = 0.45;
 export const DEFAULT_SNOW_DENSITY = 0.5;
+/** @internal */
 export function clampWeatherRatio(value) {
     if (!Number.isFinite(value))
         return 0;
@@ -11,11 +12,13 @@ export function clampWeatherRatio(value) {
         return 1;
     return value;
 }
+/** @internal */
 export function resolveWeatherInstanceCount(maxCount, density, budget) {
     const safeMax = Math.max(0, Math.floor(maxCount));
     const capped = budget === undefined ? safeMax : Math.min(safeMax, Math.max(0, Math.floor(budget)));
     return Math.floor(capped * clampWeatherRatio(density));
 }
+/** @internal */
 export function createWeatherSeedAttributes(maxCount, seed) {
     const count = Math.max(0, Math.floor(maxCount));
     const spawn = new Float32Array(count * 3);

package/dist/weather/weatherUniforms.d.ts

@@ -11,8 +11,11 @@ export interface WeatherUniformOptions {
     lightning?: number;
     timeScale?: number;
 }
+/** @internal */
 export declare function createWeatherUniformSet(options?: WeatherUniformOptions): WeatherUniformSet;
+/** @internal */
 export declare function WeatherUniformProvider({ children, ...options }: WeatherUniformOptions & {
     children: ReactNode;
 }): import("react").JSX.Element;
+/** @internal */
 export declare function useWeatherUniformSet(options?: WeatherUniformOptions): WeatherUniformSet;

package/dist/weather/weatherUniforms.js

@@ -3,6 +3,7 @@ import { createContext, useContext, useMemo } from "react";
 import { useFrame } from "@react-three/fiber";
 import * as THREE from "three";
 const WeatherUniformContext = createContext(null);
+/** @internal */
 export function createWeatherUniformSet(options = {}) {
     const wind = options.wind ?? [0, 0, 0];
     return {
@@ -21,11 +22,13 @@ function useUniformTicker(uniforms, options, enabled = true) {
         uniforms.lightning.value = options.lightning ?? 0;
     });
 }
+/** @internal */
 export function WeatherUniformProvider({ children, ...options }) {
     const uniforms = useMemo(() => createWeatherUniformSet(options), []);
     useUniformTicker(uniforms, options);
     return _jsx(WeatherUniformContext.Provider, { value: uniforms, children: children });
 }
+/** @internal */
 export function useWeatherUniformSet(options = {}) {
     const shared = useContext(WeatherUniformContext);
     const local = useMemo(() => createWeatherUniformSet(options), []);

package/dist/world/RetainedVfx.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Renders retained VFX instances (`combat.vfxInstance` ops from {@link GameContext}'s `scene.entity.vfxInstance`
+ * store) as long-lived beams whose endpoints follow live entity poses. Auto-mounted by the player shell alongside
+ * the one-shot {@link WorldSpellVfx} overlay. `upsert`/`update` mutate render resources imperatively (no per-frame
+ * React allocation); only create/stop change the mounted set, and `stop` fades out over its requested duration.
+ * Beam is the first shipped retained renderer; other kinds are ignored here for a future renderer to claim.
+ *
+ * @internal
+ */
+export declare function RetainedVfx(): import("react").JSX.Element;