@jgengine/shell 0.18.1 → 0.21.0

package/dist/scene/AuthoredScene.d.ts

@@ -1,6 +1,7 @@
 import type { EditorDocument } from "@jgengine/core/editor/index";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
 import type { AssetCatalog } from "@jgengine/core/scene/assetCatalog";
+import { type ResolveAuthoredObjectsOptions } from "@jgengine/core/world/authoredObjects";
 import type { TerrainField } from "@jgengine/core/world/terrain";
 /**
  * Resolves the document AuthoredScene renders: when a {@link getDocumentLiveSync} bus is
@@ -23,7 +24,7 @@ export interface AuthoredPathsProps {
  */
 export declare function AuthoredPaths({ document, field, kinds }: AuthoredPathsProps): import("react").JSX.Element;
 /** Props for {@link AuthoredObjects}: document, ground field, and optional lift / onExisting. */
-export interface AuthoredObjectsProps {
+export interface AuthoredObjectsProps extends ResolveAuthoredObjectsOptions {
     document: EditorDocument;
     field: TerrainField;
     /** Extra lift in meters on top of each marker's own verticalOffset (default 0). */
@@ -33,16 +34,29 @@ export interface AuthoredObjectsProps {
      * `placeAuthoredObjects` call wins and remounts stay remount-safe.
      */
     onExisting?: "throw" | "replace" | "keep";
+    /** Synchronize authored edits and remove previously owned placements absent from the document. */
+    synchronize?: boolean;
 }
 /**
  * Places every editor marker with a catalog id into `ctx.scene.object`, grounded on `field`.
  * WorldScene renders them through the game's `objectModels` seam — no bespoke place loop. Pure
  * headless twin: `resolveAuthoredObjects` / `placeAuthoredObjects`.
  */
-export declare function AuthoredObjects({ document, field, verticalOffset, onExisting, }: AuthoredObjectsProps): null;
+export declare function AuthoredObjects({ document, field, verticalOffset, onExisting, synchronize, excludeKinds, }: AuthoredObjectsProps): null;
+/**
+ * Writes the document's studio solids (city buildings and any kind with a `solids` hook) into
+ * `ctx.world.solids`, so what the studios draw also blocks the player, NPCs and physics.
+ * @capability authored-solids collision for studio-authored world content such as city volumes
+ */
+export declare function AuthoredSolids({ document, field }: {
+    document: EditorDocument;
+    field: TerrainField;
+}): null;
 /** Props for {@link AuthoredScene}: the document to render and the ground field to drape/ground on. */
 export interface AuthoredSceneProps {
     document: EditorDocument;
+    /** Register bounded procedural weather counts in the supported diagnostics probes. */
+    diagnostics?: boolean;
     field: TerrainField;
     /** Restrict rendered path kinds; default renders every non-scatter path. */
     pathKinds?: readonly string[];
@@ -52,6 +66,8 @@ export interface AuthoredSceneProps {
      * dedicated map even if it shares entries with `entityModels`). Requires `assets`.
      */
     scatterModels?: Record<string, string | ModelConfig>;
+    /** Animated models keyed by authored cosmetic habitat species. */
+    flockModels?: Record<string, string | ModelConfig>;
     /** Catalog `scatterModels` string ids resolve through; required together with `scatterModels`. */
     assets?: AssetCatalog;
     /**
@@ -63,11 +79,12 @@ export interface AuthoredSceneProps {
     /**
      * Place the document's catalog-id markers into the object
      * store — WorldScene renders them via the game's `objectModels` seam. Omit when the game places
-     * props itself in onInit with `placeAuthoredObjects`.
+     * props itself in onInit with `placeAuthoredObjects`. `excludeKinds` replaces the resolver's
+     * default mob/boss exclusions; include those when adding other game-owned entity spawn kinds.
      */
-    placeObjects?: boolean | {
+    placeObjects?: boolean | ({
         verticalOffset?: number;
-    };
+    } & ResolveAuthoredObjectsOptions);
     /** Terrain surface color sampler forwarded to studio renderers (see `SceneKindRenderContext.groundColorAt`). */
     groundColorAt?: (x: number, z: number) => string;
 }
@@ -81,4 +98,4 @@ export interface AuthoredSceneProps {
  * place markers with your own entity spawns. Pass `scatterModels`+`assets` to resolve palette items to
  * real catalog GLBs; unmapped items keep the stylized proxy.
  */
-export declare function AuthoredScene({ document, field, pathKinds, scatterModels, assets, live, placeObjects, groundColorAt, }: AuthoredSceneProps): import("react").JSX.Element;
+export declare function AuthoredScene({ document, diagnostics, field, pathKinds, scatterModels, flockModels, assets, live, placeObjects, groundColorAt, }: AuthoredSceneProps): import("react").JSX.Element;

package/dist/scene/AuthoredScene.js

@@ -1,8 +1,11 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Fragment, useCallback, useEffect, useMemo, useSyncExternalStore } from "react";
+import { AuthoredFlocks } from "../world/AuthoredFlocks.js";
+import { AuthoredWeatherLayer } from "../weather/AuthoredWeatherLayer.js";
+import { Fragment, useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
 import * as THREE from "three";
 import { getDocumentLiveSync, subscribeDocumentLiveSyncInstall, } from "@jgengine/core/editor/index";
-import { placeAuthoredObjects, resolveAuthoredObjects, } from "@jgengine/core/world/authoredObjects";
+import { placeAuthoredObjects, resolveAuthoredObjectsWithDiagnostics, syncAuthoredObjects, } from "@jgengine/core/world/authoredObjects";
+import { syncAuthoredSolids } from "@jgengine/core/world/authoredSolids";
 import { buildRoadRibbon, GROUND_DECAL_LAYERS, roundPathCorners } from "@jgengine/core/world/roads";
 import { isScatterPath, resolveScatter } from "@jgengine/core/world/scatterRegion";
 import { getAssetGenerator } from "@jgengine/core/scene/assetGenerator";
@@ -130,17 +133,47 @@ export function AuthoredPaths({ document, field, kinds }) {
  * WorldScene renders them through the game's `objectModels` seam — no bespoke place loop. Pure
  * headless twin: `resolveAuthoredObjects` / `placeAuthoredObjects`.
  */
-export function AuthoredObjects({ document, field, verticalOffset = 0, onExisting = "keep", }) {
+export function AuthoredObjects({ document, field, verticalOffset = 0, onExisting = "keep", synchronize = false, excludeKinds, }) {
     const ctx = useGameContext();
-    const objects = useMemo(() => resolveAuthoredObjects(document), [document]);
+    const previousObjects = useRef([]);
+    const previousStore = useRef(ctx.scene.object);
+    const resolved = useMemo(() => resolveAuthoredObjectsWithDiagnostics(document, excludeKinds === undefined ? {} : { excludeKinds }), [document, excludeKinds]);
+    const warnedResult = useRef(null);
+    const objects = resolved.objects;
     useEffect(() => {
-        if (objects.length === 0)
+        if (warnedResult.current !== resolved) {
+            warnedResult.current = resolved;
+            for (const diagnostic of resolved.diagnostics)
+                console.warn(`[jgengine] ${diagnostic.path}: ${diagnostic.message}. ${diagnostic.repair}`);
+        }
+        if (previousStore.current !== ctx.scene.object) {
+            previousObjects.current = [];
+            previousStore.current = ctx.scene.object;
+        }
+        if (synchronize) {
+            previousObjects.current = syncAuthoredObjects(ctx.scene.object, objects, previousObjects.current, (x, z) => field.sampleHeight(x, z), { verticalOffset });
             return;
+        }
         placeAuthoredObjects(ctx.scene.object, objects, (x, z) => field.sampleHeight(x, z), {
             verticalOffset,
             onExisting,
         });
-    }, [ctx.scene.object, field, objects, onExisting, verticalOffset]);
+    }, [ctx.scene.object, field, resolved, objects, onExisting, verticalOffset, synchronize]);
+    return null;
+}
+/**
+ * Writes the document's studio solids (city buildings and any kind with a `solids` hook) into
+ * `ctx.world.solids`, so what the studios draw also blocks the player, NPCs and physics.
+ * @capability authored-solids collision for studio-authored world content such as city volumes
+ */
+export function AuthoredSolids({ document, field }) {
+    const ctx = useGameContext();
+    useEffect(() => {
+        syncAuthoredSolids(ctx.world.solids, document, (x, z) => field.sampleHeight(x, z));
+    }, [ctx.world.solids, document, field]);
+    useEffect(() => () => {
+        syncAuthoredSolids(ctx.world.solids, { markers: [], volumes: [], paths: [] });
+    }, [ctx.world.solids]);
     return null;
 }
 /**
@@ -153,16 +186,20 @@ export function AuthoredObjects({ document, field, verticalOffset = 0, onExistin
  * place markers with your own entity spawns. Pass `scatterModels`+`assets` to resolve palette items to
  * real catalog GLBs; unmapped items keep the stylized proxy.
  */
-export function AuthoredScene({ document, field, pathKinds, scatterModels, assets, live = true, placeObjects, groundColorAt, }) {
+export function AuthoredScene({ document, diagnostics = false, field, pathKinds, scatterModels, flockModels, assets, live = true, placeObjects, groundColorAt, }) {
+    const ctx = useGameContext();
     const liveDocument = useLiveEditorDocument(document, live);
+    // Authoring updates configuration only. Physics remains owned by the fixed game-time stages.
+    useEffect(() => { ctx.environment.retune(liveDocument); }, [ctx.environment, liveDocument]);
     const instances = useMemo(() => resolveScatter(liveDocument, field), [liveDocument, field]);
     const resolveItem = useMemo(() => createModelMapResolver(scatterModels, assets, "scatterModels"), [scatterModels, assets]);
     const shouldPlaceObjects = placeObjects === true || (typeof placeObjects === "object" && placeObjects !== null);
     const objectVerticalOffset = typeof placeObjects === "object" && placeObjects !== null ? (placeObjects.verticalOffset ?? 0) : 0;
-    return (_jsxs(_Fragment, { children: [_jsx(AuthoredPaths, { document: liveDocument, field: field, ...(pathKinds === undefined ? {} : { kinds: pathKinds }) }), _jsx(InstancedScatter, { instances: instances, ...(resolveItem === undefined ? {} : { resolveItem }) }), _jsx(AuthoredStudios, { document: liveDocument, context: {
+    const objectExcludeKinds = typeof placeObjects === "object" && placeObjects !== null ? placeObjects.excludeKinds : undefined;
+    return (_jsxs(_Fragment, { children: [_jsx(AuthoredWeatherLayer, { document: liveDocument, heightAt: field.sampleHeight, diagnostics: diagnostics }), flockModels === undefined ? null : _jsx(AuthoredFlocks, { models: flockModels, assets: assets }), _jsx(AuthoredPaths, { document: liveDocument, field: field, ...(pathKinds === undefined ? {} : { kinds: pathKinds }) }), _jsx(InstancedScatter, { instances: instances, ...(resolveItem === undefined ? {} : { resolveItem }) }), _jsx(AuthoredStudios, { document: liveDocument, context: {
                     document: liveDocument,
                     field,
                     ...(assets === undefined ? {} : { assets }),
                     ...(groundColorAt === undefined ? {} : { groundColorAt }),
-                } }), _jsx(AuthoredGenerators, { document: liveDocument, field: field }), shouldPlaceObjects ? (_jsx(AuthoredObjects, { document: liveDocument, field: field, verticalOffset: objectVerticalOffset })) : null] }));
+                } }), _jsx(AuthoredGenerators, { document: liveDocument, field: field }), _jsx(AuthoredSolids, { document: liveDocument, field: field }), shouldPlaceObjects ? (_jsx(AuthoredObjects, { document: liveDocument, field: field, verticalOffset: objectVerticalOffset, synchronize: live && getDocumentLiveSync() !== null, ...(objectExcludeKinds === undefined ? {} : { excludeKinds: objectExcludeKinds }) })) : null] }));
 }

package/dist/scene/CityRenderer.js

@@ -22,7 +22,7 @@ import { offsetPath } from "@jgengine/core/world/streets";
 import { triangulatePolygon, triangulateRingBand } from "@jgengine/core/world/cityGeometry";
 import { resolveCityObject, CITY_KIND, CITY_ZONE_KIND, } from "@jgengine/core/world/cityKind";
 import { zoneBand, zoneMetric } from "@jgengine/core/world/cityContent";
-import { generateBuilding, resolveBuildingPalette, resolveBuildingWallTones, } from "@jgengine/core/world/buildings";
+import { generateBuilding, buildingSurfaceColor, resolveBuildingPalette, resolveBuildingWallTones, } from "@jgengine/core/world/buildings";
 import { hashString } from "@jgengine/core/random/rng";
 import { buildScatterProxy } from "../scatter/scatterProxies.js";
 import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
@@ -327,12 +327,12 @@ function unitGeometries() {
 const ROLE_JITTER = { wall: 1, roof: 0.5, trim: 0.35, accent: 0.6 };
 function roleColor(palette, role) {
     if (role === "wall")
-        return palette.wall;
+        return buildingSurfaceColor(palette.wall);
     if (role === "roof")
-        return palette.roof;
+        return buildingSurfaceColor(palette.roof);
     if (role === "trim")
-        return palette.corner;
-    return palette.awning;
+        return buildingSurfaceColor(palette.corner);
+    return buildingSurfaceColor(palette.awning);
 }
 const DETAIL_RADIUS = 95;
 const DETAIL_MAX = 12;
@@ -547,7 +547,7 @@ function OneCity({ object, context }) {
             return mesh;
         };
         const plain = new THREE.MeshStandardMaterial({ roughness: 0.85, metalness: 0.04 });
-        const banded = createCityWindowMaterial({ floorHeight: resolved.rules.floorHeight, windowColor: palette.window });
+        const banded = createCityWindowMaterial({ floorHeight: resolved.rules.floorHeight, windowColor: buildingSurfaceColor(palette.window) });
         const meshes = [
             makeMesh("box", units.box, plain),
             makeMesh("banded", units.box, banded),

package/dist/scene/GeneratedAssetRenderer.js

@@ -1,49 +1,18 @@
-import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useMemo, useRef } from "react";
-import * as THREE from "three";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
 import { resolveGeneratorAsset } from "@jgengine/core/scene/assetGenerator";
-const UNIT_BOX = new THREE.BoxGeometry(1, 1, 1);
+import { StaticShapeInstances } from "../render/staticShapeInstances.js";
 const NEUTRAL = "#b8b0a4";
 /** All parts of one generated asset, batched into one instanced box draw per color. */
 function GeneratedParts({ asset }) {
-    const byColor = useMemo(() => {
-        const groups = new Map();
-        for (const part of asset.parts) {
-            const color = part.color ?? NEUTRAL;
-            const bucket = groups.get(color);
-            if (bucket === undefined)
-                groups.set(color, [part]);
-            else
-                bucket.push(part);
-        }
-        return [...groups.entries()];
-    }, [asset]);
-    return (_jsx(_Fragment, { children: byColor.map(([color, parts]) => (_jsx(ColorBatch, { color: color, parts: parts }, color))) }));
-}
-function ColorBatch({ color, parts }) {
-    const meshRef = useRef(null);
-    useEffect(() => {
-        const mesh = meshRef.current;
-        if (mesh === null)
-            return;
-        const matrix = new THREE.Matrix4();
-        const position = new THREE.Vector3();
-        const quaternion = new THREE.Quaternion();
-        const euler = new THREE.Euler();
-        const scale = new THREE.Vector3();
-        parts.forEach((part, index) => {
-            position.set(part.position[0], part.position[1], part.position[2]);
-            euler.set(0, part.rotationY ?? 0, 0);
-            quaternion.setFromEuler(euler);
-            scale.set(Math.max(1e-3, part.size[0]), Math.max(1e-3, part.size[1]), Math.max(1e-3, part.size[2]));
-            matrix.compose(position, quaternion, scale);
-            mesh.setMatrixAt(index, matrix);
-        });
-        mesh.count = parts.length;
-        mesh.instanceMatrix.needsUpdate = true;
-        mesh.computeBoundingSphere();
-    }, [parts]);
-    return (_jsx("instancedMesh", { ref: meshRef, args: [UNIT_BOX, undefined, Math.max(1, parts.length)], castShadow: true, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: color, roughness: 0.62, metalness: 0.04 }) }));
+    const instances = useMemo(() => asset.parts.map(part => ({
+        shape: "box",
+        position: part.position,
+        rotation: [0, part.rotationY ?? 0, 0],
+        scale: [Math.max(1e-3, part.size[0]), Math.max(1e-3, part.size[1]), Math.max(1e-3, part.size[2])],
+        surface: { color: part.color ?? NEUTRAL, roughness: 0.62, metalness: 0.04 },
+    })), [asset]);
+    return _jsx(StaticShapeInstances, { instances: instances });
 }
 /**
  * Renders one placed generator-asset instance by re-resolving its `meta` through the registered

package/dist/settings/QuickControls.js

@@ -14,7 +14,7 @@ function QuickToggle({ row }) {
 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) => {
+    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 flex-wrap justify-end 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));
                 }) })] }));

package/dist/settings/SettingsMenu.js

@@ -1,5 +1,7 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from "react";
+import { ScrollRail } from "@jgengine/react/scrollRail";
+import { useDialogBehavior } from "@jgengine/react/dialogBehavior";
 import { useDebouncedCommit } from "@jgengine/react/useDebouncedCommit";
 import {} from "./settingsController.js";
 const surface = "var(--jg-surface, #16161d)";
@@ -40,9 +42,9 @@ function ToggleRow({ row }) {
 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) => {
+    return (_jsx(RowShell, { label: row.label, control: _jsx("div", { role: "group", "aria-label": row.label, className: "flex flex-wrap justify-end 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));
+                return (_jsx("button", { type: "button", onClick: () => row.set(option.value), "aria-pressed": selected, 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 }) {
@@ -68,10 +70,10 @@ function ActionRow({ action, onClose }) {
         }, 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 }));
+    return (_jsx("button", { type: "button", onClick: onSelect, className: `shrink-0 min-h-[44px] 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
+    return (_jsx("div", { className: "jg-settings-scroll min-h-0 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)))] })) }));
 }
@@ -95,6 +97,7 @@ export function SettingsMenu({ controller, onClose, initialTab, }) {
     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;
+    const dialogRef = useDialogBehavior({ open: active !== null, onClose: capturing === null ? onClose : undefined });
     useEffect(() => {
         if (capturing === null)
             return;
@@ -124,28 +127,18 @@ export function SettingsMenu({ controller, onClose, initialTab, }) {
             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 })] }) }));
+        return (_jsx("div", { ref: dialogRef, role: "dialog", "aria-modal": "true", "aria-label": "Settings", tabIndex: -1, 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(ScrollRail, { label: "settings categories", style: { paddingBottom: 16 }, 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 })] })] }) }));
+        return (_jsx(Backdrop, { onClose: onClose, align: "items-center", children: _jsxs("div", { ref: dialogRef, role: "dialog", "aria-modal": "true", "aria-label": "Settings", tabIndex: -1, 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 overflow-y-auto 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 min-w-0 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-end", children: _jsxs("div", { ref: dialogRef, role: "dialog", "aria-modal": "true", "aria-label": "Settings", tabIndex: -1, 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(ScrollRail, { label: "settings categories", style: { padding: "0 16px 12px" }, 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 })] }) }));
+    return (_jsx(Backdrop, { onClose: onClose, align: "items-center", children: _jsxs("div", { ref: dialogRef, role: "dialog", "aria-modal": "true", "aria-label": "Settings", tabIndex: -1, 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(ScrollRail, { label: "settings categories", style: { padding: "12px 16px", 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

@@ -1,4 +1,5 @@
 import { type ReactNode } from "react";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
 import type { SettingsSurface, SettingsVariant } from "@jgengine/core/settings/settingsModel";
 import { type SettingsActionView } from "@jgengine/react/settings";
 import { type SettingsControllerInput } from "./settingsController.js";
@@ -9,3 +10,7 @@ export interface SettingsRuntimeProps extends SettingsControllerInput {
     children: ReactNode;
 }
 export declare function SettingsRuntime({ variant, surface, actions, children, ...input }: SettingsRuntimeProps): import("react").JSX.Element;
+/** Owns settings' suspension for this live context, including close, replacement and unmount. @internal */
+export declare function SettingsPlayControlGate({ ctx }: {
+    ctx: GameContext;
+}): import("react").JSX.Element;

package/dist/settings/SettingsRuntime.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useMemo, useState } from "react";
-import { SettingsControllerProvider, } from "@jgengine/react/settings";
+import { useLayoutEffect, useMemo, useRef, useState } from "react";
+import { suspendPlayControls } from "@jgengine/core/game/controlGate";
+import { SettingsControllerProvider, useSettings, } from "@jgengine/react/settings";
+import { createPlaySurfaceFocusOwnership } from "../presentationRecovery.js";
 import { useSettingsCategories } from "./settingsController.js";
 export function SettingsRuntime({ variant, surface, actions, children, ...input }) {
     const categories = useSettingsCategories(input);
@@ -17,3 +19,28 @@ export function SettingsRuntime({ variant, surface, actions, children, ...input
     }), [categories, actions, variant, surface, isOpen]);
     return _jsx(SettingsControllerProvider, { controller: controller, children: children });
 }
+/** Owns settings' suspension for this live context, including close, replacement and unmount. @internal */
+export function SettingsPlayControlGate({ ctx }) {
+    const { isOpen } = useSettings();
+    const anchor = useRef(null);
+    const openedSurface = useRef(null);
+    const focus = useRef(createPlaySurfaceFocusOwnership());
+    useLayoutEffect(() => {
+        if (isOpen) {
+            openedSurface.current = { owner: ctx, surface: anchor.current?.closest('div[tabindex="0"]') ?? null };
+            return;
+        }
+        const previous = openedSurface.current;
+        openedSurface.current = null;
+        if (previous?.owner !== ctx)
+            return;
+        focus.current.request(ctx);
+        focus.current.reveal(ctx, previous.surface, document.activeElement, document.body);
+    }, [ctx, isOpen]);
+    useLayoutEffect(() => {
+        if (!isOpen)
+            return;
+        return suspendPlayControls(ctx);
+    }, [ctx, isOpen]);
+    return _jsx("span", { hidden: true, ref: anchor });
+}

package/dist/settings/appliedSettings.d.ts

@@ -1,6 +1,7 @@
 import type { AudioBusDef } from "@jgengine/core/audio/audioFalloff";
 import { type GraphicsQuality, type SettingsStore } from "@jgengine/core/settings/settingsModel";
-import { type GraphicsProfile } from "@jgengine/core/settings/graphicsProfile";
+import type { GraphicsProfile } from "@jgengine/core/settings/graphicsProfile";
+import { type GraphicsProfileOverrides } from "@jgengine/core/settings/graphicsSettings";
 import { type TouchJoystickVariant, type TouchStyle } from "@jgengine/core/input/touchScheme";
 import type { AudioEngine } from "../audio/audioEngine.js";
 /** Sentinel Controls value meaning "defer to the game's suggested touch skin". */
@@ -10,13 +11,18 @@ export declare function useTouchStyle(store: SettingsStore, fallback: TouchStyle
 /** Shell-internal: binds the SettingsStore joystick-variant choice (fixed vs floating) to the touch renderer. @internal */
 export declare function useTouchJoystickVariant(store: SettingsStore): TouchJoystickVariant;
 export declare function useSettingsRevision(store: SettingsStore): number;
-export declare function useGraphicsSettings(store: SettingsStore, shadowsDefault: boolean, overrides?: Partial<Record<GraphicsQuality, Partial<GraphicsProfile>>>): {
+/** The player's graphics choices as the shell applies them. */
+export interface AppliedGraphicsSettings {
     shadows: boolean;
     dpr: number;
     uiScale: number;
     quality: GraphicsQuality;
     profile: GraphicsProfile;
-};
+    /** Frames-per-second cap; 0 renders every display refresh. */
+    frameRateLimit: number;
+    showFps: boolean;
+}
+export declare function useGraphicsSettings(store: SettingsStore, shadowsDefault: boolean, overrides?: GraphicsProfileOverrides): AppliedGraphicsSettings;
 export declare function AudioSettingsBridge({ store, engine, buses, }: {
     store: SettingsStore;
     engine: AudioEngine;

package/dist/settings/appliedSettings.js

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useSyncExternalStore } 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";
-import { resolveGraphicsProfile } from "@jgengine/core/settings/graphicsProfile";
+import { busVolumeSettingId, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
+import { readGraphicsSettings } from "@jgengine/core/settings/graphicsSettings";
+import { readFrameRateLimit } from "@jgengine/core/settings/frameRateLimit";
 import { DEFAULT_TOUCH_JOYSTICK_VARIANT, TOUCH_JOYSTICK_VARIANTS, TOUCH_STYLES, } from "@jgengine/core/input/touchScheme";
 /** Sentinel Controls value meaning "defer to the game's suggested touch skin". */
 export const TOUCH_STYLE_AUTO = "auto";
@@ -29,9 +30,7 @@ export function useSettingsRevision(store) {
 }
 export function useGraphicsSettings(store, shadowsDefault, overrides) {
     useSettingsRevision(store);
-    const rawQuality = store.get(SETTING_IDS.graphicsQuality, DEFAULT_GRAPHICS_QUALITY);
-    const quality = GRAPHICS_QUALITY_DPR[rawQuality] !== undefined ? rawQuality : "high";
-    const profile = resolveGraphicsProfile(quality, overrides?.[quality]);
+    const { quality, profile } = readGraphicsSettings(store, overrides);
     const rawUiScale = store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE);
     return {
         shadows: store.get(SETTING_IDS.graphicsShadows, shadowsDefault),
@@ -39,6 +38,8 @@ export function useGraphicsSettings(store, shadowsDefault, overrides) {
         uiScale: Math.min(UI_SCALE_MAX, Math.max(UI_SCALE_MIN, rawUiScale)),
         quality,
         profile,
+        frameRateLimit: readFrameRateLimit(store),
+        showFps: store.get(SETTING_IDS.graphicsShowFps, false),
     };
 }
 export function AudioSettingsBridge({ store, engine, buses, }) {

package/dist/settings/settingsController.d.ts

@@ -2,6 +2,7 @@ import { bindingLabel, type ActionCodesMap } from "@jgengine/core/input/actionBi
 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 GraphicsProfileOverrides } from "@jgengine/core/settings/graphicsSettings";
 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 {
@@ -11,6 +12,8 @@ export interface SettingsControllerInput {
     categories: readonly SettingCategoryDef[];
     hide: readonly SettingCategory[];
     fovEnabled: boolean;
+    /** The game's per-tier profile overrides (`defineGame({ graphics })`), so tier defaults match what renders. */
+    graphics?: GraphicsProfileOverrides;
     hideBindings: readonly string[];
     /** Show the touch-controls skin selector in Controls (touch device with a dock). */
     touchStyle: boolean;

package/dist/settings/settingsController.js

@@ -1,5 +1,7 @@
 import { actionLabel, bindingLabel } from "@jgengine/core/input/actionBindings";
-import { BUILT_IN_SETTING_CATEGORIES, busVolumeSettingId, DEFAULT_GRAPHICS_QUALITY, DEFAULT_GRAPHICS_SHADOWS, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
+import { BUILT_IN_SETTING_CATEGORIES, busVolumeSettingId, DEFAULT_GRAPHICS_SHADOWS, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
+import { ANISOTROPY_OPTIONS, applyGraphicsQuality, GRAPHICS_POST_STAGE_LABELS, GRAPHICS_POST_STAGES, graphicsPostStageSettingId, readGraphicsSettings, RENDER_SCALE_MAX, RENDER_SCALE_MIN, RENDER_SCALE_STEP, } from "@jgengine/core/settings/graphicsSettings";
+import { FRAME_RATE_LIMIT_DISPLAY, FRAME_RATE_LIMIT_OPTIONS } from "@jgengine/core/settings/frameRateLimit";
 import { DEFAULT_TOUCH_JOYSTICK_VARIANT, TOUCH_JOYSTICK_VARIANT_OPTIONS, TOUCH_STYLE_OPTIONS, } from "@jgengine/core/input/touchScheme";
 import { TOUCH_STYLE_AUTO, useSettingsRevision } from "./appliedSettings.js";
 import { useSettingsStore, } from "@jgengine/react/settings";
@@ -61,14 +63,42 @@ export function useSettingsCategories(config) {
         }),
         ...extrasFor("sound"),
     ];
+    const graphics = readGraphicsSettings(store, config.graphics);
     const graphicsRows = [
         {
             id: SETTING_IDS.graphicsQuality,
             label: "Quality",
             kind: "select",
-            value: store.get(SETTING_IDS.graphicsQuality, DEFAULT_GRAPHICS_QUALITY),
+            value: graphics.quality,
             options: GRAPHICS_QUALITY_OPTIONS,
-            set: (value) => store.set(SETTING_IDS.graphicsQuality, value),
+            set: (value) => applyGraphicsQuality(store, String(value), config.graphics),
+        },
+        {
+            id: SETTING_IDS.graphicsRenderScale,
+            label: "Render scale",
+            kind: "slider",
+            value: graphics.profile.renderScale,
+            min: RENDER_SCALE_MIN,
+            max: RENDER_SCALE_MAX,
+            step: RENDER_SCALE_STEP,
+            format: percent,
+            set: (value) => store.set(SETTING_IDS.graphicsRenderScale, value),
+        },
+        {
+            id: SETTING_IDS.graphicsFrameRateLimit,
+            label: "Frame rate limit",
+            kind: "select",
+            value: store.get(SETTING_IDS.graphicsFrameRateLimit, FRAME_RATE_LIMIT_DISPLAY),
+            options: FRAME_RATE_LIMIT_OPTIONS,
+            set: (value) => store.set(SETTING_IDS.graphicsFrameRateLimit, String(value)),
+        },
+        {
+            id: SETTING_IDS.graphicsAnisotropy,
+            label: "Texture filtering",
+            kind: "select",
+            value: String(graphics.profile.anisotropy),
+            options: ANISOTROPY_OPTIONS,
+            set: (value) => store.set(SETTING_IDS.graphicsAnisotropy, String(value)),
         },
         {
             id: SETTING_IDS.graphicsShadows,
@@ -77,6 +107,13 @@ export function useSettingsCategories(config) {
             value: store.get(SETTING_IDS.graphicsShadows, DEFAULT_GRAPHICS_SHADOWS),
             set: (value) => store.set(SETTING_IDS.graphicsShadows, value),
         },
+        ...GRAPHICS_POST_STAGES.map((stage) => ({
+            id: graphicsPostStageSettingId(stage),
+            label: GRAPHICS_POST_STAGE_LABELS[stage],
+            kind: "toggle",
+            value: graphics.profile.postStages[stage],
+            set: (value) => store.set(graphicsPostStageSettingId(stage), value),
+        })),
         {
             id: SETTING_IDS.graphicsUiScale,
             label: "UI scale",
@@ -88,6 +125,13 @@ export function useSettingsCategories(config) {
             format: percent,
             set: (value) => store.set(SETTING_IDS.graphicsUiScale, value),
         },
+        {
+            id: SETTING_IDS.graphicsShowFps,
+            label: "Show FPS",
+            kind: "toggle",
+            value: store.get(SETTING_IDS.graphicsShowFps, false),
+            set: (value) => store.set(SETTING_IDS.graphicsShowFps, value),
+        },
         ...extrasFor("graphics"),
     ];
     const gameplayRows = [

package/dist/shellControlSuspension.d.ts

@@ -0,0 +1,18 @@
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { PointerAxisState } from "@jgengine/core/input/pointerAxis";
+type Ref<T> = {
+    current: T;
+};
+/** Clears held input synchronously on play-gate transitions; ordinary context swaps retain it. @internal */
+export declare function attachShellControlSuspension({ ctx, tracker, pointerAxisRef, analogRef, primaryClickRef, cameraDraggingRef, f2HeldRef, }: {
+    ctx: GameContext;
+    tracker: {
+        reset(): void;
+    };
+    pointerAxisRef: Ref<PointerAxisState | null>;
+    analogRef: Ref<Readonly<Record<string, number>> | null>;
+    primaryClickRef: Ref<boolean>;
+    cameraDraggingRef: Ref<boolean>;
+    f2HeldRef: Ref<boolean>;
+}): () => void;
+export {};