@jgengine/shell 0.9.0 → 0.11.0

package/dist/terrain/terrainDetailMaterial.js

@@ -0,0 +1,157 @@
+import * as THREE from "three";
+const NOISE_GLSL = /* glsl */ `
+uint jgHashUint(uvec2 v){
+  uint x = v.x * 1664525u + v.y * 1013904223u;
+  x = (x ^ (x >> 16u)) * 2246822519u;
+  x = (x ^ (x >> 13u)) * 3266489917u;
+  x = x ^ (x >> 16u);
+  return x;
+}
+float jgHash(vec2 p){
+  ivec2 i = ivec2(floor(p));
+  return float(jgHashUint(uvec2(i))) * (1.0 / 4294967296.0);
+}
+float jgVNoise(vec2 p){
+  vec2 i = floor(p); vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  float a = jgHash(i);
+  float b = jgHash(i + vec2(1.0, 0.0));
+  float c = jgHash(i + vec2(0.0, 1.0));
+  float d = jgHash(i + vec2(1.0, 1.0));
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+}
+float jgFbm(vec2 p){
+  float v = 0.0; float amp = 0.5;
+  for (int i = 0; i < 4; i++){ v += amp * jgVNoise(p); p *= 2.0; amp *= 0.5; }
+  return v;
+}
+`;
+/**
+ * A `MeshStandardMaterial` whose fragment shader keeps the biome-tinted vertex
+ * colour as the base ground and blends procedural, noise-broken rock (by slope),
+ * sand (by waterline), and snow (by height) over it — textured-reading terrain
+ * with no image assets. Full PBR: lit, shadowed, and fogged like any standard
+ * material, so it composes with the post-processing chain.
+ *
+ * When `detail.material` is set, pass the matching loaded `textures` (color/normal/roughness/ao):
+ * they tile by world position at `detail.material.repeat` world units per tile and blend over the
+ * procedural result at `detail.material.strength` — the real-texture seam layers onto the existing
+ * look instead of replacing it.
+  * @internal
+  */
+export function createTerrainDetailMaterial(detail, textures) {
+    const hasTexture = textures !== undefined && detail.material !== undefined;
+    const repeat = detail.material?.repeat ?? 4;
+    const strength = detail.material?.strength ?? 1;
+    const uniforms = {
+        uRockColor: { value: new THREE.Color(detail.rockColor) },
+        uSandColor: { value: new THREE.Color(detail.sandColor) },
+        uSnowColor: { value: new THREE.Color(detail.snowColor) },
+        uRockSlopeStart: { value: detail.rockSlopeStart },
+        uSnowHeight: { value: detail.snowHeight },
+        uWaterLevel: { value: detail.waterLevel },
+        uDetailScale: { value: Math.max(0.5, detail.detailScale) },
+        uMacroScale: { value: Math.max(0.5, detail.macroScale) },
+        uStrength: { value: detail.strength },
+        ...(hasTexture
+            ? {
+                uMatColor: { value: textures.color },
+                uMatNormal: { value: textures.normal },
+                uMatRoughness: { value: textures.roughness },
+                uMatAo: { value: textures.ao },
+                uMatRepeat: { value: Math.max(0.01, repeat) },
+                uMatStrength: { value: strength },
+            }
+            : {}),
+    };
+    const material = new THREE.MeshStandardMaterial({
+        color: "#ffffff",
+        roughness: detail.roughness,
+        metalness: 0,
+        vertexColors: true,
+    });
+    material.onBeforeCompile = (shader) => {
+        Object.assign(shader.uniforms, uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `#include <common>
+varying vec3 vJgWorldPos;
+varying vec3 vJgWorldNormal;`)
+            .replace("#include <beginnormal_vertex>", `#include <beginnormal_vertex>
+vJgWorldNormal = normalize(mat3(modelMatrix) * objectNormal);`)
+            .replace("#include <begin_vertex>", `#include <begin_vertex>
+vJgWorldPos = (modelMatrix * vec4(transformed, 1.0)).xyz;`);
+        const materialUniformsGlsl = hasTexture
+            ? `
+uniform sampler2D uMatColor;
+uniform sampler2D uMatNormal;
+uniform sampler2D uMatRoughness;
+uniform sampler2D uMatAo;
+uniform float uMatRepeat;
+uniform float uMatStrength;`
+            : "";
+        const materialColorGlsl = hasTexture
+            ? `
+vec2 jgMatUv = jgWp / uMatRepeat;
+vec3 jgMatColor = texture2D(uMatColor, jgMatUv).rgb;
+jgCol = mix(jgCol, jgMatColor, uMatStrength);`
+            : "";
+        const materialRoughnessGlsl = hasTexture
+            ? `
+float jgMatRough = texture2D(uMatRoughness, jgMatUv).g;
+roughnessFactor = mix(roughnessFactor, jgMatRough, uMatStrength);`
+            : "";
+        const materialNormalGlsl = hasTexture
+            ? `
+vec2 jgMatNormalXy = texture2D(uMatNormal, jgMatUv).rg * 2.0 - 1.0;
+normal = normalize(normal + vec3(jgMatNormalXy.x, 0.0, jgMatNormalXy.y) * uMatStrength * 0.6);`
+            : "";
+        const materialAoGlsl = hasTexture
+            ? `
+float jgMatAo = texture2D(uMatAo, jgMatUv).r;
+reflectedLight.indirectDiffuse *= mix(1.0, jgMatAo, uMatStrength);`
+            : "";
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `#include <common>
+varying vec3 vJgWorldPos;
+varying vec3 vJgWorldNormal;
+uniform vec3 uRockColor;
+uniform vec3 uSandColor;
+uniform vec3 uSnowColor;
+uniform float uRockSlopeStart;
+uniform float uSnowHeight;
+uniform float uWaterLevel;
+uniform float uDetailScale;
+uniform float uMacroScale;
+uniform float uStrength;
+${materialUniformsGlsl}
+${NOISE_GLSL}`)
+            .replace("#include <color_fragment>", `#include <color_fragment>
+vec2 jgWp = vJgWorldPos.xz;
+float jgFine = jgFbm(jgWp / uDetailScale);
+float jgMacro = jgFbm(jgWp / uMacroScale);
+float jgSlope = 1.0 - clamp(vJgWorldNormal.y, 0.0, 1.0);
+float jgH = vJgWorldPos.y;
+vec3 jgBase = diffuseColor.rgb;
+jgBase *= mix(1.0 - 0.22 * uStrength, 1.0 + 0.18 * uStrength, jgFine);
+jgBase = mix(jgBase, jgBase * vec3(0.86, 0.9, 0.82), jgMacro * 0.25 * uStrength);
+vec3 jgRock = uRockColor * mix(0.72, 1.15, jgFbm(jgWp / (uDetailScale * 1.7)));
+float jgRockW = smoothstep(uRockSlopeStart, uRockSlopeStart + 0.18, jgSlope) * uStrength;
+vec3 jgCol = mix(jgBase, jgRock, jgRockW);
+vec3 jgSand = uSandColor * mix(0.9, 1.08, jgFine);
+float jgSandW = smoothstep(uWaterLevel + 2.4, uWaterLevel - 0.4, jgH) * (1.0 - jgRockW) * uStrength;
+jgCol = mix(jgCol, jgSand, jgSandW);
+vec3 jgSnow = uSnowColor * mix(0.94, 1.04, jgFine);
+float jgSnowW = smoothstep(uSnowHeight, uSnowHeight + 8.0, jgH) * (1.0 - jgRockW * 0.6) * uStrength;
+jgCol = mix(jgCol, jgSnow, jgSnowW);
+${materialColorGlsl}
+diffuseColor.rgb = jgCol;`)
+            .replace("#include <roughnessmap_fragment>", `#include <roughnessmap_fragment>
+${materialRoughnessGlsl}`)
+            .replace("#include <normal_fragment_maps>", `#include <normal_fragment_maps>
+${materialNormalGlsl}`)
+            .replace("#include <aomap_fragment>", `#include <aomap_fragment>
+${materialAoGlsl}`);
+    };
+    material.customProgramCacheKey = () => `jgengine-terrain-detail-${detail.rockSlopeStart}-${detail.snowHeight}-${hasTexture ? "tex" : "flat"}`;
+    return { material };
+}

package/dist/terrain/terrainMath.d.ts

@@ -27,10 +27,15 @@ export interface TerrainVertexColorOptions {
     waterline?: THREE.ColorRepresentation;
     waterlineHeight?: number;
 }
+/** @internal */
 export declare function normalizeHeightBlend(height: number, minHeight: number, maxHeight: number): number;
+/** @internal */
 export declare function resolveTerrainSize(size?: TerrainArea): ResolvedTerrainSize;
+/** @internal */
 export declare function resolveTerrainSegments(segments?: ProceduralTerrainConfig["segments"]): ResolvedTerrainSegments;
+/** @internal */
 export declare function toNoiseFieldConfig(config?: ProceduralTerrainConfig): NoiseFieldConfig;
+/** @internal */
 export declare function createProceduralTerrainSampler(config?: ProceduralTerrainConfig): TerrainHeightSampler;
 /** Per-position palette override for multi-biome ground coloring — `createTerrainPaletteSampler` from `@jgengine/core/world/terrain` returns exactly this shape. */
 export type TerrainPaletteSampler = (x: number, z: number) => {
@@ -51,6 +56,8 @@ export interface FieldGroundOptions {
  * Mesh any `TerrainField` — including a `CarvableField` with craters/mounds written into it — into a
  * vertex-coloured ground geometry. `sampleHeight` drives the vertices, so runtime carves show up as
  * real depressions the moment the field is re-sampled (bump the caller's rebuild key after a carve).
- */
+  * @internal
+  */
 export declare function createFieldGroundGeometry(field: TerrainField, options?: FieldGroundOptions): THREE.BufferGeometry;
+/** @internal */
 export declare function createProceduralGroundGeometry(config?: ProceduralTerrainConfig, colors?: TerrainVertexColorOptions): THREE.BufferGeometry;

package/dist/terrain/terrainMath.js

@@ -1,21 +1,25 @@
 import { noiseField } from "@jgengine/core/world/terrain";
 import * as THREE from "three";
 import {} from "./random.js";
+/** @internal */
 export function normalizeHeightBlend(height, minHeight, maxHeight) {
     const range = maxHeight - minHeight;
     if (range <= 1e-6)
         return 0.5;
     return THREE.MathUtils.clamp((height - minHeight) / range, 0, 1);
 }
+/** @internal */
 export function resolveTerrainSize(size = 40) {
     return typeof size === "number" ? { width: size, depth: size } : { width: size[0], depth: size[1] };
 }
+/** @internal */
 export function resolveTerrainSegments(segments = 96) {
     if (typeof segments !== "number")
         return { x: Math.max(1, Math.floor(segments[0])), z: Math.max(1, Math.floor(segments[1])) };
     const resolved = Math.max(1, Math.floor(segments));
     return { x: resolved, z: resolved };
 }
+/** @internal */
 export function toNoiseFieldConfig(config = {}) {
     return {
         seed: config.seed,
@@ -26,6 +30,7 @@ export function toNoiseFieldConfig(config = {}) {
         baseHeight: config.baseOffset ?? 0,
     };
 }
+/** @internal */
 export function createProceduralTerrainSampler(config = {}) {
     return noiseField(toNoiseFieldConfig(config)).sampleHeight;
 }
@@ -33,7 +38,8 @@ export function createProceduralTerrainSampler(config = {}) {
  * Mesh any `TerrainField` — including a `CarvableField` with craters/mounds written into it — into a
  * vertex-coloured ground geometry. `sampleHeight` drives the vertices, so runtime carves show up as
  * real depressions the moment the field is re-sampled (bump the caller's rebuild key after a carve).
- */
+  * @internal
+  */
 export function createFieldGroundGeometry(field, options = {}) {
     const size = resolveTerrainSize(options.size);
     const segments = resolveTerrainSegments(options.segments);
@@ -118,6 +124,7 @@ function buildGroundGeometry(size, segments, sampler, opts) {
     geometry.computeBoundingSphere();
     return geometry;
 }
+/** @internal */
 export function createProceduralGroundGeometry(config = {}, colors = {}) {
     const size = resolveTerrainSize(config.size);
     const segments = resolveTerrainSegments(config.segments);

package/dist/touch/TouchControlsOverlay.d.ts

@@ -1,5 +1,5 @@
 import { type MutableRefObject } from "react";
-import { type TouchScheme } from "@jgengine/core/input/touchScheme";
+import { type TouchScheme, type TouchStyle } from "@jgengine/core/input/touchScheme";
 export interface TouchCodeSink {
     onCodeDown(code: string): void;
     onCodeUp(code: string): void;
@@ -14,9 +14,11 @@ export declare function primaryButtonOffsets(count: number, scale?: number): {
     bottom: number;
 }[] | null;
 /**
- * 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 declare function touchDockClearance(scheme: TouchScheme | null, scale?: number): number;
 export declare function TouchPlaySurface({ scheme, sink, yawRef, pitchRef, maxPitch, onPrimaryTap, }: {
@@ -27,8 +29,10 @@ export declare function TouchPlaySurface({ scheme, sink, yawRef, pitchRef, maxPi
     maxPitch: number;
     onPrimaryTap: () => void;
 }): import("react").JSX.Element;
-export declare function TouchControlsDock({ scheme, sink, scale }: {
+export declare function TouchControlsDock({ scheme, sink, style, scale, }: {
     scheme: TouchScheme;
     sink: TouchCodeSink;
+    /** Player-selected skin; falls back to the scheme's game default. */
+    style?: TouchStyle;
     scale?: number;
 }): import("react").JSX.Element;

package/dist/touch/TouchControlsOverlay.js

@@ -1,15 +1,20 @@
 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" };
+const ACTIONS_ZONE = { id: "control:actions", kind: "control", collisionPolicy: "forbid", collisionGroup: "touch-dock" };
+const UTILITY_ZONE = { id: "control:utility", kind: "control", collisionPolicy: "warn", collisionGroup: "touch-dock" };
 const JOYSTICK_SIZE = 132;
 const JOYSTICK_THUMB = 52;
 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;
@@ -17,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 {
@@ -59,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;
@@ -154,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);
@@ -196,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;
@@ -212,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)
@@ -221,59 +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");
-    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", { children: scheme.joystick !== null ? _jsx(VirtualJoystick, { joystick: scheme.joystick, sink: sink, scale: scale }) : null }), _jsx(PrimaryButtonCluster, { buttons: primary, sink: sink, scale: scale })] }), utility.length > 0 ? (_jsx("div", { className: "pointer-events-none absolute inset-x-0 flex justify-center gap-2", style: { bottom: "calc(env(safe-area-inset-bottom, 0px) + 8px)" }, children: utility.map((button) => (_jsx(TouchUtilityChip, { button: button, sink: sink }, button.action))) })) : null] }));
+/** 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);
+    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;