@jgengine/shell 0.8.0 → 0.9.0

package/dist/input/mouseLook.d.ts

@@ -0,0 +1,27 @@
+export interface MouseLookOptions {
+    /** Radians of look per pixel of mouse movement; default `0.0024`. */
+    sensitivity?: number;
+    /** Pitch clamp in radians; default `1.15`. */
+    maxPitch?: number;
+    /** Request pointer lock on click (skipped on coarse-pointer/touch devices); default `true`. */
+    pointerLock?: boolean;
+    initialYaw?: number;
+    initialPitch?: number;
+}
+export interface MouseLookAim {
+    yaw: number;
+    pitch: number;
+}
+/**
+ * The analog mouse-look service chase/orbit-cam games hand-rolled (#282.8) — pointer-lock
+ * lifecycle plus delta accumulation into a yaw/pitch aim, decoupled from the first-person rig.
+ * Attach it to the canvas, read `aim()` from `onTick`/`useFrame`, dispose on unmount.
+ */
+export interface MouseLookTracker {
+    aim(): MouseLookAim;
+    setAim(yaw: number, pitch: number): void;
+    /** True while pointer lock is held on the tracked element. */
+    locked(): boolean;
+    dispose(): void;
+}
+export declare function createMouseLookTracker(element: HTMLElement, options?: MouseLookOptions): MouseLookTracker;

package/dist/input/mouseLook.js

@@ -0,0 +1,35 @@
+export function createMouseLookTracker(element, options = {}) {
+    const sensitivity = options.sensitivity ?? 0.0024;
+    const maxPitch = options.maxPitch ?? 1.15;
+    const pointerLock = options.pointerLock ?? true;
+    let yaw = options.initialYaw ?? 0;
+    let pitch = options.initialPitch ?? 0;
+    const requestLock = () => {
+        if (!pointerLock)
+            return;
+        if (window.matchMedia?.("(pointer: coarse)").matches)
+            return;
+        if (document.pointerLockElement !== element)
+            void element.requestPointerLock?.();
+    };
+    const onMove = (event) => {
+        if (pointerLock && document.pointerLockElement !== element)
+            return;
+        yaw -= event.movementX * sensitivity;
+        pitch = Math.max(-maxPitch, Math.min(maxPitch, pitch - event.movementY * sensitivity));
+    };
+    element.addEventListener("click", requestLock);
+    window.addEventListener("mousemove", onMove);
+    return {
+        aim: () => ({ yaw, pitch }),
+        setAim(nextYaw, nextPitch) {
+            yaw = nextYaw;
+            pitch = Math.max(-maxPitch, Math.min(maxPitch, nextPitch));
+        },
+        locked: () => document.pointerLockElement === element,
+        dispose() {
+            element.removeEventListener("click", requestLock);
+            window.removeEventListener("mousemove", onMove);
+        },
+    };
+}

package/dist/materialOverride.d.ts

@@ -1,8 +1,6 @@
 import * as THREE from "three";
 import type { ModelMaterialOverride } from "@jgengine/core/game/playableGame";
-/**
- * Clones each `MeshStandardMaterial` under `root` and applies `override`'s
- * color/finish onto the clone, so shared GLTF-cache scenes are never mutated
- * in place (#151.3).
- */
-export declare function applyMaterialOverride(root: THREE.Object3D, override: ModelMaterialOverride): void;
+export interface MaterialOverrideOptions {
+    clone?: boolean;
+}
+export declare function applyMaterialOverride(root: THREE.Object3D, override: ModelMaterialOverride, options?: MaterialOverrideOptions): void;

package/dist/materialOverride.js

@@ -1,32 +1,28 @@
 import * as THREE from "three";
-/**
- * Clones each `MeshStandardMaterial` under `root` and applies `override`'s
- * color/finish onto the clone, so shared GLTF-cache scenes are never mutated
- * in place (#151.3).
- */
-export function applyMaterialOverride(root, override) {
+export function applyMaterialOverride(root, override, options) {
+    const clone = options?.clone !== false;
     root.traverse((node) => {
         const mesh = node;
         if (!mesh.isMesh)
             return;
         mesh.material = Array.isArray(mesh.material)
-            ? mesh.material.map((material) => overrideOne(material, override))
-            : overrideOne(mesh.material, override);
+            ? mesh.material.map((material) => overrideOne(material, override, clone))
+            : overrideOne(mesh.material, override, clone);
     });
 }
-function overrideOne(material, override) {
+function overrideOne(material, override, clone) {
     if (!(material instanceof THREE.MeshStandardMaterial))
         return material;
-    const clone = material.clone();
+    const target = clone ? material.clone() : material;
     if (override.color !== undefined)
-        clone.color.set(override.color);
+        target.color.set(override.color);
     if (override.metalness !== undefined)
-        clone.metalness = override.metalness;
+        target.metalness = override.metalness;
     if (override.roughness !== undefined)
-        clone.roughness = override.roughness;
+        target.roughness = override.roughness;
     if (override.emissive !== undefined)
-        clone.emissive.set(override.emissive);
+        target.emissive.set(override.emissive);
     if (override.emissiveIntensity !== undefined)
-        clone.emissiveIntensity = override.emissiveIntensity;
-    return clone;
+        target.emissiveIntensity = override.emissiveIntensity;
+    return target;
 }

package/dist/pointer/PointerProbe.js

@@ -5,7 +5,12 @@ export function PointerProbe({ service }) {
     const scene = useThree((state) => state.scene);
     const gl = useThree((state) => state.gl);
     const size = useThree((state) => state.size);
-    service.bind({ camera, scene, width: size.width, height: size.height });
+    useEffect(() => {
+        service.bind({ camera, scene, width: size.width, height: size.height });
+        return () => {
+            service.bind(null);
+        };
+    }, [service, camera, scene, size.width, size.height]);
     useEffect(() => {
         const el = gl.domElement;
         let locked = false;
@@ -33,7 +38,6 @@ export function PointerProbe({ service }) {
             el.removeEventListener("pointermove", onMove);
             el.removeEventListener("pointerleave", onLeave);
             document.removeEventListener("pointerlockchange", onLockChange);
-            service.bind(null);
         };
     }, [gl, service]);
     return null;

package/dist/pointer/pointerService.d.ts

@@ -2,11 +2,14 @@ import * as THREE from "three";
 import type { PointerHit, PointerVec3 } from "@jgengine/core/input/pointer";
 export declare const POINTER_ENTITY_KEY = "jgEntityId";
 export declare const POINTER_OBJECT_KEY = "jgObjectId";
+export type PointerHitFilter = (object: THREE.Object3D) => boolean;
 interface PointerDeps {
     camera: THREE.Camera;
     scene: THREE.Scene;
     width: number;
     height: number;
+    layers?: THREE.Layers;
+    filter?: PointerHitFilter;
 }
 export interface PointerService {
     /** Cast the current cursor into the world; null when the cursor is off-canvas. */

package/dist/pointer/pointerService.js

@@ -30,9 +30,15 @@ export function createPointerService() {
     function hitAtNdc(target) {
         if (deps === null)
             return null;
+        if (deps.layers !== undefined)
+            raycaster.layers.mask = deps.layers.mask;
+        else
+            raycaster.layers.enableAll();
         raycaster.setFromCamera(target, deps.camera);
         const intersects = raycaster.intersectObjects(deps.scene.children, true);
         for (const hit of intersects) {
+            if (deps.filter !== undefined && !deps.filter(hit.object))
+                continue;
             const mesh = hit.object;
             if (!mesh.isMesh)
                 continue;

package/dist/render/modelRender.d.ts

@@ -1,8 +1,17 @@
 import * as THREE from "three";
 import type { PaintStroke } from "@jgengine/core/scene/paintLayer";
 export declare const PAINT_TEXTURE_SIZE = 512;
-export declare function cloneModelScene(source: THREE.Object3D): THREE.Object3D;
+export declare function cloneModelScene(source: THREE.Object3D, options?: {
+    cloneMaterials?: boolean;
+}): THREE.Object3D;
+export declare function disposeClonedMaterials(root: THREE.Object3D): void;
 export declare function standardMaterialsOf(root: THREE.Object3D): THREE.MeshStandardMaterial[];
+export interface MaterialCache {
+    materials: THREE.MeshStandardMaterial[];
+    seedColor: THREE.Color;
+}
+export declare function cacheStandardMaterials(root: THREE.Object3D, into?: MaterialCache | null): MaterialCache;
+export declare function applyPaintTextureToMaterials(materials: readonly THREE.MeshStandardMaterial[], paint: PaintCanvas): void;
 export interface PaintCanvas {
     canvas: HTMLCanvasElement;
     context: CanvasRenderingContext2D;

package/dist/render/modelRender.js

@@ -1,8 +1,10 @@
 import * as THREE from "three";
 import { clone as cloneSkinned } from "three/examples/jsm/utils/SkeletonUtils.js";
 export const PAINT_TEXTURE_SIZE = 512;
-export function cloneModelScene(source) {
+export function cloneModelScene(source, options) {
     const clone = cloneSkinned(source);
+    if (options?.cloneMaterials === false)
+        return clone;
     clone.traverse((node) => {
         const mesh = node;
         if (!mesh.isMesh)
@@ -13,6 +15,21 @@ export function cloneModelScene(source) {
     });
     return clone;
 }
+export function disposeClonedMaterials(root) {
+    const seen = new Set();
+    root.traverse((node) => {
+        const mesh = node;
+        if (!mesh.isMesh)
+            return;
+        const list = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        for (const material of list) {
+            if (seen.has(material))
+                continue;
+            seen.add(material);
+            material.dispose();
+        }
+    });
+}
 function isMeshStandardMaterial(material) {
     return material.isMeshStandardMaterial === true;
 }
@@ -29,6 +46,19 @@ export function standardMaterialsOf(root) {
     });
     return materials;
 }
+export function cacheStandardMaterials(root, into) {
+    if (into !== null && into !== undefined)
+        return into;
+    const materials = standardMaterialsOf(root);
+    const seedColor = materials[0]?.color.clone() ?? new THREE.Color("#ffffff");
+    return { materials, seedColor };
+}
+export function applyPaintTextureToMaterials(materials, paint) {
+    for (const material of materials) {
+        material.map = paint.texture;
+        material.needsUpdate = true;
+    }
+}
 export function createPaintCanvas(seed, size = PAINT_TEXTURE_SIZE) {
     const canvas = document.createElement("canvas");
     canvas.width = size;
@@ -57,10 +87,7 @@ export function drawPaintStrokes(paint, strokes) {
     texture.needsUpdate = true;
 }
 export function applyPaintTexture(root, paint) {
-    for (const material of standardMaterialsOf(root)) {
-        material.map = paint.texture;
-        material.needsUpdate = true;
-    }
+    applyPaintTextureToMaterials(standardMaterialsOf(root), paint);
 }
 export function syncPaintCanvas(paint, seedColor, strokes, drawnCount) {
     if (strokes.length < drawnCount) {

package/dist/render/resolveModel.d.ts

@@ -0,0 +1,14 @@
+import type { AssetCatalog } from "@jgengine/core/scene/assetCatalog";
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+export interface ModelResolveContext {
+    seam: "entityModels" | "objectModels";
+    key: string;
+}
+/**
+ * Resolve a string asset id or a direct ModelConfig. Missing/misspelled catalog
+ * ids throw — silent generic-primitive fallback only happens when the mapping
+ * omits the key entirely (or uses tryResolveCatalogModel for optional ids).
+ */
+export declare function resolveModel(value: string | ModelConfig | undefined, assets: AssetCatalog, context?: ModelResolveContext): ModelConfig | undefined;
+/** Soft lookup used when an object catalog id may double as a model asset id. */
+export declare function tryResolveCatalogModel(id: string, assets: AssetCatalog): ModelConfig | undefined;

package/dist/render/resolveModel.js

@@ -0,0 +1,24 @@
+/**
+ * Resolve a string asset id or a direct ModelConfig. Missing/misspelled catalog
+ * ids throw — silent generic-primitive fallback only happens when the mapping
+ * omits the key entirely (or uses tryResolveCatalogModel for optional ids).
+ */
+export function resolveModel(value, assets, context) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        return value;
+    const ref = assets.resolve(value);
+    if (ref === null) {
+        const where = context === undefined ? `model asset "${value}"` : `${context.seam}["${context.key}"] → "${value}"`;
+        throw new Error(`[jgengine] missing ${where} — not in the asset catalog. Fix the id, register it, or omit the mapping to keep the deliberate primitive/sprite fallback.`);
+    }
+    return ref.dims === undefined ? { url: ref.url } : { url: ref.url, dims: ref.dims };
+}
+/** Soft lookup used when an object catalog id may double as a model asset id. */
+export function tryResolveCatalogModel(id, assets) {
+    const ref = assets.resolve(id);
+    if (ref === null)
+        return undefined;
+    return ref.dims === undefined ? { url: ref.url } : { url: ref.url, dims: ref.dims };
+}

package/dist/settings/QuickControls.d.ts

@@ -0,0 +1,4 @@
+import type { SettingsController } from "./settingsController.js";
+export declare function QuickControls({ controller }: {
+    controller: SettingsController;
+}): import("react").JSX.Element | null;

package/dist/settings/QuickControls.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+function QuickSlider({ row }) {
+    const value = Number(row.value);
+    const readout = row.format?.(value) ?? String(value);
+    return (_jsxs("label", { className: "flex items-center gap-2 text-xs text-neutral-300", children: [_jsx("span", { className: "w-16 shrink-0 truncate", children: row.label }), _jsx("input", { type: "range", min: row.min, max: row.max, step: row.step, value: value, "aria-label": row.label, className: "h-1.5 flex-1 cursor-pointer accent-emerald-400", onChange: (event) => row.set(Number(event.target.value)) }), _jsx("span", { className: "w-9 shrink-0 text-right tabular-nums text-neutral-100", children: readout })] }));
+}
+function QuickToggle({ row }) {
+    const on = Boolean(row.value);
+    return (_jsxs("div", { className: "flex items-center justify-between gap-2 text-xs text-neutral-300", children: [_jsx("span", { className: "truncate", children: row.label }), _jsx("button", { type: "button", role: "switch", "aria-checked": on, "aria-label": row.label, onClick: () => row.set(!on), className: `relative h-6 w-11 shrink-0 rounded-full ring-1 transition ${on ? "bg-emerald-500 ring-emerald-400" : "bg-neutral-700 ring-white/10"}`, children: _jsx("span", { className: `absolute top-1 h-4 w-4 rounded-full bg-white shadow transition-all ${on ? "left-6" : "left-1"}` }) })] }));
+}
+function QuickSelect({ row }) {
+    const options = row.options ?? [];
+    const current = String(row.value);
+    return (_jsxs("div", { className: "flex items-center justify-between gap-2 text-xs text-neutral-300", children: [_jsx("span", { className: "truncate", children: row.label }), _jsx("div", { className: "flex shrink-0 gap-1 rounded-md bg-neutral-950/60 p-0.5 ring-1 ring-white/10", children: options.map((option) => {
+                    const selected = option.value === current;
+                    return (_jsx("button", { type: "button", onClick: () => row.set(option.value), className: `rounded px-2 py-1 font-medium transition ${selected ? "bg-emerald-500 text-neutral-950" : "text-neutral-300 hover:bg-neutral-800"}`, children: option.label }, option.value));
+                }) })] }));
+}
+function QuickRow({ row }) {
+    if (row.kind === "slider")
+        return _jsx(QuickSlider, { row: row });
+    if (row.kind === "toggle")
+        return _jsx(QuickToggle, { row: row });
+    return _jsx(QuickSelect, { row: row });
+}
+function Popover({ children }) {
+    return (_jsx("div", { className: "absolute bottom-12 left-0 w-64 space-y-2.5 rounded-lg bg-neutral-950/90 p-3 shadow-2xl ring-1 ring-white/10 backdrop-blur-sm", children: children }));
+}
+function QuickButton({ label, open, onToggle, children, }) {
+    return (_jsx("button", { type: "button", onClick: onToggle, "aria-label": label, "aria-pressed": open, className: `flex h-11 w-11 items-center justify-center rounded-md text-lg shadow-lg ring-1 backdrop-blur-sm transition ${open ? "bg-emerald-500/20 text-emerald-300 ring-emerald-400/50" : "bg-neutral-950/75 text-neutral-200 ring-white/10 hover:bg-neutral-900/80"}`, children: children }));
+}
+export function QuickControls({ controller }) {
+    const [open, setOpen] = useState(null);
+    const byId = (id) => controller.categories.find((category) => category.id === id);
+    const sound = byId("sound");
+    const graphics = byId("graphics");
+    if (sound === undefined && graphics === undefined)
+        return null;
+    const toggle = (which) => setOpen((current) => (current === which ? null : which));
+    return (_jsxs("div", { className: "pointer-events-auto absolute bottom-3 left-3 z-30 flex items-end gap-2", children: [sound !== undefined ? (_jsxs("div", { className: "relative", children: [open === "volume" ? (_jsx(Popover, { children: sound.rows.map((row) => (_jsx(QuickRow, { row: row }, row.id))) })) : null, _jsx(QuickButton, { label: "Volume", open: open === "volume", onToggle: () => toggle("volume"), children: _jsx("span", { "aria-hidden": true, children: "\uD83D\uDD0A" }) })] })) : null, graphics !== undefined ? (_jsxs("div", { className: "relative", children: [open === "graphics" ? (_jsx(Popover, { children: graphics.rows.map((row) => (_jsx(QuickRow, { row: row }, row.id))) })) : null, _jsx(QuickButton, { label: "Graphics", open: open === "graphics", onToggle: () => toggle("graphics"), children: _jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 1.8, strokeLinecap: "round", strokeLinejoin: "round", className: "h-5 w-5", "aria-hidden": true, children: [_jsx("circle", { cx: "12", cy: "12", r: "9" }), _jsx("path", { d: "M12 3a9 9 0 0 0 0 18M3 12h18M5 6c2 1.5 5 2.5 7 2.5S17 7.5 19 6M5 18c2-1.5 5-2.5 7-2.5s5 1 7 2.5" })] }) })] })) : null] }));
+}

package/dist/settings/SettingsChrome.d.ts

@@ -0,0 +1 @@
+export declare function SettingsChrome(): import("react").JSX.Element | null;

package/dist/settings/SettingsChrome.js

@@ -0,0 +1,10 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useSettings } from "@jgengine/react/settings";
+import { QuickControls } from "./QuickControls.js";
+import { SettingsMenu } from "./SettingsMenu.js";
+export function SettingsChrome() {
+    const settings = useSettings();
+    if (settings.categories.length === 0 && settings.actions.length === 0)
+        return null;
+    return (_jsxs(_Fragment, { children: [settings.surface === "quick" ? _jsx(QuickControls, { controller: settings }) : null, settings.isOpen ? _jsx(SettingsMenu, { controller: settings, onClose: settings.close }) : null] }));
+}

package/dist/settings/SettingsMenu.d.ts

@@ -0,0 +1,6 @@
+import { type SettingsController } from "./settingsController.js";
+export declare function SettingsMenu({ controller, onClose, initialTab, }: {
+    controller: SettingsController;
+    onClose: () => void;
+    initialTab?: string;
+}): import("react").JSX.Element | null;

package/dist/settings/SettingsMenu.js

@@ -0,0 +1,148 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import {} from "./settingsController.js";
+const surface = "var(--jg-surface, #16161d)";
+const surfaceDeep = "var(--jg-surface-deep, #0b0b11)";
+const edge = "var(--jg-edge, #2b2b35)";
+const text = "var(--jg-text, #ececef)";
+const textDim = "var(--jg-text-dim, #9494a0)";
+const accent = "var(--jg-accent, #6ee7a8)";
+const accentGlow = "var(--jg-accent-glow, rgba(110,231,168,0.35))";
+const onAccent = "var(--jg-surface-deep, #0b0b0f)";
+const danger = "var(--jg-danger, #e0574e)";
+const fontDisplay = "var(--jg-font-display, inherit)";
+const rowStyle = { background: "rgba(255,255,255,0.045)", border: "1px solid rgba(255,255,255,0.08)" };
+const badgeStyle = { background: surfaceDeep, border: "1px solid rgba(255,255,255,0.12)", color: text };
+function GlyphClose() {
+    return (_jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", className: "h-4 w-4", "aria-hidden": true, children: _jsx("path", { d: "M6 6l12 12M18 6L6 18" }) }));
+}
+function GlyphReset() {
+    return (_jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round", className: "h-3.5 w-3.5", "aria-hidden": true, children: [_jsx("path", { d: "M3 12a9 9 0 1 0 3-6.7L3 8" }), _jsx("path", { d: "M3 3v5h5" })] }));
+}
+function CloseButton({ onClose }) {
+    return (_jsx("button", { type: "button", onClick: onClose, "aria-label": "Close settings", className: "flex h-9 w-9 shrink-0 items-center justify-center rounded-lg transition hover:bg-white/10", style: { color: textDim, border: "1px solid rgba(255,255,255,0.1)" }, children: _jsx(GlyphClose, {}) }));
+}
+function RowShell({ label, control }) {
+    return (_jsxs("div", { className: "flex items-center justify-between gap-4 rounded-xl px-3.5 py-3", style: rowStyle, children: [_jsx("span", { className: "text-sm", style: { color: text }, children: label }), control] }));
+}
+function SliderRow({ row }) {
+    const value = Number(row.value);
+    const readout = row.format?.(value) ?? String(value);
+    return (_jsx(RowShell, { label: row.label, control: _jsxs("div", { className: "flex flex-1 items-center gap-3 pl-4", children: [_jsx("input", { type: "range", min: row.min, max: row.max, step: row.step, value: value, "aria-label": row.label, className: "h-1.5 flex-1 cursor-pointer", style: { accentColor: accent }, onChange: (event) => row.set(Number(event.target.value)) }), _jsx("span", { className: "w-12 shrink-0 text-right text-sm tabular-nums", style: { color: text }, children: readout })] }) }));
+}
+function ToggleRow({ row }) {
+    const on = Boolean(row.value);
+    return (_jsx(RowShell, { label: row.label, control: _jsx("button", { type: "button", role: "switch", "aria-checked": on, "aria-label": row.label, onClick: () => row.set(!on), className: "relative h-7 w-12 shrink-0 rounded-full transition", style: { background: on ? accent : "rgba(255,255,255,0.16)", boxShadow: on ? `0 0 12px ${accentGlow}` : "none" }, children: _jsx("span", { className: `absolute top-1 h-5 w-5 rounded-full bg-white shadow transition-all ${on ? "left-6" : "left-1"}` }) }) }));
+}
+function SelectRow({ row }) {
+    const options = row.options ?? [];
+    const current = String(row.value);
+    return (_jsx(RowShell, { label: row.label, control: _jsx("div", { className: "flex shrink-0 gap-1 rounded-lg p-1", style: { background: surfaceDeep }, children: options.map((option) => {
+                const selected = option.value === current;
+                return (_jsx("button", { type: "button", onClick: () => row.set(option.value), className: "min-h-[34px] rounded-md px-3 text-sm font-medium transition", style: selected ? { background: accent, color: onAccent } : { color: textDim }, children: option.label }, option.value));
+            }) }) }));
+}
+function RowControl({ row }) {
+    if (row.kind === "slider")
+        return _jsx(SliderRow, { row: row });
+    if (row.kind === "toggle")
+        return _jsx(ToggleRow, { row: row });
+    return _jsx(SelectRow, { row: row });
+}
+function KeybindRowView({ row, capturing, onCapture, }) {
+    return (_jsxs("div", { className: "flex items-center justify-between gap-3 rounded-xl px-3.5 py-3", style: rowStyle, children: [_jsx("span", { className: "text-sm", style: { color: text }, children: row.label }), _jsxs("div", { className: "flex shrink-0 items-center gap-2", children: [_jsx("button", { type: "button", onClick: onCapture, disabled: capturing, title: "Click to rebind \u2014 Esc to cancel", className: "inline-flex min-h-[34px] min-w-[3.75rem] items-center justify-center rounded-lg px-3 font-mono text-sm transition hover:brightness-125", style: capturing
+                            ? { background: accentGlow, color: accent, border: `1px solid ${accent}` }
+                            : badgeStyle, children: capturing ? "Press…" : row.bindingLabel }), _jsx("button", { type: "button", onClick: () => row.reset(), "aria-label": `Reset ${row.label}`, title: "Reset to default", className: `flex h-8 w-8 items-center justify-center rounded-lg transition hover:bg-white/10 ${row.isDefault ? "invisible" : ""}`, style: { color: textDim }, children: _jsx(GlyphReset, {}) })] })] }));
+}
+function ActionRow({ action, onClose }) {
+    const isDanger = action.kind === "danger";
+    return (_jsxs("button", { type: "button", onClick: () => {
+            action.run();
+            onClose();
+        }, className: "flex w-full items-center justify-between gap-3 rounded-xl px-4 py-3.5 text-left transition hover:brightness-110", style: {
+            background: isDanger ? "rgba(224,87,78,0.12)" : "rgba(255,255,255,0.05)",
+            border: `1px solid ${isDanger ? danger : "rgba(255,255,255,0.1)"}`,
+        }, children: [_jsxs("span", { className: "flex flex-col gap-0.5", children: [_jsx("span", { className: "text-sm font-semibold", style: { color: isDanger ? danger : text }, children: action.label }), action.description !== undefined ? (_jsx("span", { className: "text-xs", style: { color: textDim }, children: action.description })) : null] }), _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round", className: "h-4 w-4 shrink-0", style: { color: isDanger ? danger : textDim }, "aria-hidden": true, children: _jsx("path", { d: "M9 6l6 6-6 6" }) })] }));
+}
+function TabButton({ tab, selected, orientation, onSelect }) {
+    return (_jsx("button", { type: "button", onClick: onSelect, className: `min-h-[40px] whitespace-nowrap rounded-lg px-4 text-sm font-medium transition ${orientation === "col" ? "w-full text-left" : ""} ${selected ? "" : "hover:bg-white/5"}`, style: selected ? { background: accent, color: onAccent } : { color: textDim }, children: tab.label }));
+}
+function Body({ tab, actions, capturing, setCapturing, onClose }) {
+    return (_jsx("div", { className: "jg-settings-scroll flex-1 space-y-2 overflow-y-auto p-4", children: tab.category === null
+            ? actions.map((action) => _jsx(ActionRow, { action: action, onClose: onClose }, action.id))
+            : (_jsxs(_Fragment, { children: [tab.category.rows.map((row) => (_jsx(RowControl, { row: row }, row.id))), tab.category.keybinds.map((row) => (_jsx(KeybindRowView, { row: row, capturing: capturing?.action === row.action, onCapture: () => setCapturing(row) }, row.action)))] })) }));
+}
+const panelStyle = {
+    background: surface,
+    color: text,
+    border: `1px solid ${edge}`,
+    fontFamily: fontDisplay,
+};
+function Backdrop({ children, onClose, align }) {
+    return (_jsx("div", { className: `pointer-events-auto absolute inset-0 z-40 flex justify-center bg-black/55 p-3 backdrop-blur-sm ${align}`, onClick: onClose, children: children }));
+}
+function stop(event) {
+    event.stopPropagation();
+}
+export function SettingsMenu({ controller, onClose, initialTab, }) {
+    const tabs = [
+        ...(controller.actions.length > 0 ? [{ id: "game", label: "Game", category: null }] : []),
+        ...controller.categories.map((category) => ({ id: category.id, label: category.label, category })),
+    ];
+    const [activeId, setActiveId] = useState(initialTab !== undefined && tabs.some((tab) => tab.id === initialTab) ? initialTab : (tabs[0]?.id ?? ""));
+    const [capturing, setCapturing] = useState(null);
+    const active = tabs.find((tab) => tab.id === activeId) ?? tabs[0] ?? null;
+    useEffect(() => {
+        if (capturing === null)
+            return;
+        const onKey = (event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            if (event.code === "Escape") {
+                setCapturing(null);
+                return;
+            }
+            capturing.rebind(event.code);
+            setCapturing(null);
+        };
+        const onPointer = (event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            capturing.rebind(`mouse${event.button}`);
+            setCapturing(null);
+        };
+        const onContext = (event) => event.preventDefault();
+        window.addEventListener("keydown", onKey, true);
+        window.addEventListener("pointerdown", onPointer, true);
+        window.addEventListener("contextmenu", onContext, true);
+        return () => {
+            window.removeEventListener("keydown", onKey, true);
+            window.removeEventListener("pointerdown", onPointer, true);
+            window.removeEventListener("contextmenu", onContext, true);
+        };
+    }, [capturing]);
+    useEffect(() => {
+        if (capturing !== null)
+            return;
+        const onKey = (event) => {
+            if (event.code === "Escape")
+                onClose();
+        };
+        window.addEventListener("keydown", onKey);
+        return () => window.removeEventListener("keydown", onKey);
+    }, [capturing, onClose]);
+    if (active === null)
+        return null;
+    const bodyProps = { tab: active, actions: controller.actions, capturing, setCapturing, onClose };
+    const title = (_jsx("h2", { className: "text-base font-semibold tracking-wide", style: { color: text }, children: "Settings" }));
+    if (controller.variant === "fullscreen") {
+        return (_jsx("div", { className: "pointer-events-auto absolute inset-0 z-40 flex flex-col", style: { background: surface, color: text, fontFamily: fontDisplay }, children: _jsxs("div", { className: "mx-auto flex h-full w-full max-w-2xl flex-col px-4", children: [_jsxs("div", { className: "flex items-center justify-between gap-3 pb-4 pt-6", children: [_jsx("h2", { className: "text-2xl font-bold tracking-wide", style: { color: text }, children: "Settings" }), _jsx(CloseButton, { onClose: onClose })] }), _jsx("div", { className: "flex gap-1.5 overflow-x-auto pb-4", children: tabs.map((tab) => (_jsx(TabButton, { tab: tab, selected: tab.id === active.id, orientation: "row", onSelect: () => setActiveId(tab.id) }, tab.id))) }), _jsx(Body, { ...bodyProps })] }) }));
+    }
+    if (controller.variant === "sidebar") {
+        return (_jsx(Backdrop, { onClose: onClose, align: "items-center", children: _jsxs("div", { onClick: stop, className: "flex overflow-hidden rounded-2xl shadow-2xl", style: { ...panelStyle, width: "min(94vw, 760px)", height: "min(84vh, 560px)" }, children: [_jsxs("nav", { className: "flex w-44 shrink-0 flex-col gap-1 p-3", style: { background: surfaceDeep, borderRight: `1px solid ${edge}` }, children: [_jsx("span", { className: "px-3 pb-2 pt-1 text-xs font-semibold uppercase tracking-widest", style: { color: textDim }, children: "Settings" }), tabs.map((tab) => (_jsx(TabButton, { tab: tab, selected: tab.id === active.id, orientation: "col", onSelect: () => setActiveId(tab.id) }, tab.id)))] }), _jsxs("div", { className: "flex flex-1 flex-col", children: [_jsxs("div", { className: "flex items-center justify-between gap-3 px-4 py-3", style: { borderBottom: `1px solid ${edge}` }, children: [_jsx("span", { className: "text-sm font-semibold", style: { color: text }, children: active.label }), _jsx(CloseButton, { onClose: onClose })] }), _jsx(Body, { ...bodyProps })] })] }) }));
+    }
+    if (controller.variant === "sheet") {
+        return (_jsx(Backdrop, { onClose: onClose, align: "items-end", children: _jsxs("div", { onClick: stop, className: "flex flex-col overflow-hidden rounded-t-3xl shadow-2xl", style: { ...panelStyle, width: "min(100%, 640px)", height: "min(84vh, 620px)" }, children: [_jsx("div", { className: "flex flex-col items-center pt-2.5", children: _jsx("span", { className: "h-1.5 w-10 rounded-full", style: { background: "rgba(255,255,255,0.25)" } }) }), _jsxs("div", { className: "flex items-center justify-between gap-3 px-4 py-3", children: [title, _jsx(CloseButton, { onClose: onClose })] }), _jsx("div", { className: "flex gap-1.5 overflow-x-auto px-4 pb-3", children: tabs.map((tab) => (_jsx(TabButton, { tab: tab, selected: tab.id === active.id, orientation: "row", onSelect: () => setActiveId(tab.id) }, tab.id))) }), _jsx("div", { style: { borderTop: `1px solid ${edge}` }, className: "flex flex-1 flex-col overflow-hidden", children: _jsx(Body, { ...bodyProps }) })] }) }));
+    }
+    return (_jsx(Backdrop, { onClose: onClose, align: "items-center", children: _jsxs("div", { onClick: stop, className: "flex flex-col overflow-hidden rounded-2xl shadow-2xl", style: { ...panelStyle, width: "min(92vw, 460px)", height: "min(86vh, 580px)" }, children: [_jsxs("div", { className: "flex items-center justify-between gap-3 px-4 py-3.5", style: { borderBottom: `1px solid ${edge}` }, children: [title, _jsx(CloseButton, { onClose: onClose })] }), _jsx("div", { className: "flex gap-1.5 overflow-x-auto px-4 py-3", style: { borderBottom: `1px solid ${edge}` }, children: tabs.map((tab) => (_jsx(TabButton, { tab: tab, selected: tab.id === active.id, orientation: "row", onSelect: () => setActiveId(tab.id) }, tab.id))) }), _jsx(Body, { ...bodyProps })] }) }));
+}

package/dist/settings/SettingsRuntime.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from "react";
+import type { SettingsSurface, SettingsVariant } from "@jgengine/core/settings/settingsModel";
+import { type SettingsActionView } from "@jgengine/react/settings";
+import { type SettingsControllerInput } from "./settingsController.js";
+export interface SettingsRuntimeProps extends SettingsControllerInput {
+    variant: SettingsVariant;
+    surface: SettingsSurface | false;
+    actions: readonly SettingsActionView[];
+    children: ReactNode;
+}
+export declare function SettingsRuntime({ variant, surface, actions, children, ...input }: SettingsRuntimeProps): import("react").JSX.Element;

package/dist/settings/SettingsRuntime.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo, useState } from "react";
+import { SettingsControllerProvider, } from "@jgengine/react/settings";
+import { useSettingsCategories } from "./settingsController.js";
+export function SettingsRuntime({ variant, surface, actions, children, ...input }) {
+    const categories = useSettingsCategories(input);
+    const [isOpen, setOpen] = useState(false);
+    const controller = useMemo(() => ({
+        categories,
+        actions: [...actions],
+        variant,
+        surface,
+        isOpen,
+        open: () => setOpen(true),
+        close: () => setOpen(false),
+        setOpen,
+    }), [categories, actions, variant, surface, isOpen]);
+    return _jsx(SettingsControllerProvider, { controller: controller, children: children });
+}

package/dist/settings/appliedSettings.d.ts

@@ -0,0 +1,14 @@
+import type { AudioBusDef } from "@jgengine/core/audio/audioFalloff";
+import { type SettingsStore } from "@jgengine/core/settings/settingsModel";
+import type { AudioEngine } from "../audio/audioEngine.js";
+export declare function useSettingsRevision(store: SettingsStore): number;
+export declare function useGraphicsSettings(store: SettingsStore, shadowsDefault: boolean): {
+    shadows: boolean;
+    dpr: number;
+    uiScale: number;
+};
+export declare function AudioSettingsBridge({ store, engine, buses, }: {
+    store: SettingsStore;
+    engine: AudioEngine;
+    buses: Record<string, AudioBusDef> | undefined;
+}): null;

package/dist/settings/appliedSettings.js

@@ -0,0 +1,27 @@
+import { useEffect, useReducer } from "react";
+import { busVolumeSettingId, DEFAULT_GRAPHICS_QUALITY, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_DPR, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
+export function useSettingsRevision(store) {
+    const [rev, bump] = useReducer((n) => n + 1, 0);
+    useEffect(() => store.subscribe(() => bump()), [store]);
+    return rev;
+}
+export function useGraphicsSettings(store, shadowsDefault) {
+    useSettingsRevision(store);
+    const quality = store.get(SETTING_IDS.graphicsQuality, DEFAULT_GRAPHICS_QUALITY);
+    const rawUiScale = store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE);
+    return {
+        shadows: store.get(SETTING_IDS.graphicsShadows, shadowsDefault),
+        dpr: GRAPHICS_QUALITY_DPR[quality] ?? GRAPHICS_QUALITY_DPR.high,
+        uiScale: Math.min(UI_SCALE_MAX, Math.max(UI_SCALE_MIN, rawUiScale)),
+    };
+}
+export function AudioSettingsBridge({ store, engine, buses, }) {
+    const rev = useSettingsRevision(store);
+    useEffect(() => {
+        engine.setMasterGain(store.get(SETTING_IDS.masterVolume, DEFAULT_MASTER_VOLUME));
+        for (const bus of Object.values(buses ?? {})) {
+            engine.setBusGain(bus.id, store.get(busVolumeSettingId(bus.id), bus.gain ?? 1));
+        }
+    }, [store, engine, buses, rev]);
+    return null;
+}

package/dist/settings/settingsController.d.ts

@@ -0,0 +1,20 @@
+import { bindingLabel, type ActionCodesMap } from "@jgengine/core/input/actionBindings";
+import type { BindingOverrides } from "@jgengine/core/input/bindingOverrides";
+import type { AudioBusDef } from "@jgengine/core/audio/audioFalloff";
+import { type GameSettingDef, type SettingCategory, type SettingCategoryDef } from "@jgengine/core/settings/settingsModel";
+import { type SettingsActionView, type SettingsKeybindRow, type SettingsCategoryView, type SettingsController, type SettingsRow } from "@jgengine/react/settings";
+export type { SettingsActionView, SettingsKeybindRow, SettingsCategoryView, SettingsController, SettingsRow };
+export interface SettingsControllerInput {
+    input: ActionCodesMap;
+    buses: Record<string, AudioBusDef> | undefined;
+    extra: readonly GameSettingDef[];
+    categories: readonly SettingCategoryDef[];
+    hide: readonly SettingCategory[];
+    fovEnabled: boolean;
+    hideBindings: readonly string[];
+    overrides: BindingOverrides;
+    rebind: (action: string, code: string) => void;
+    resetBinding: (action: string) => void;
+}
+export declare function useSettingsCategories(config: SettingsControllerInput): SettingsCategoryView[];
+export { bindingLabel };