@jgengine/shell 0.19.0 → 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,13 +34,15 @@ 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.
@@ -52,6 +55,8 @@ export declare function AuthoredSolids({ document, field }: {
 /** 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[];
@@ -61,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;
     /**
@@ -72,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;
 }
@@ -90,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,10 @@
 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";
@@ -131,17 +133,32 @@ 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;
 }
 /**
@@ -169,16 +186,20 @@ export function AuthoredSolids({ document, field }) {
  * 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 }), _jsx(AuthoredSolids, { 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/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/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 flex-wrap justify-end 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/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 {};

package/dist/shellControlSuspension.js

@@ -0,0 +1,28 @@
+import { actionContextStack, playControlsActive } from "@jgengine/core/game/controlGate";
+/** Clears held input synchronously on play-gate transitions; ordinary context swaps retain it. @internal */
+export function attachShellControlSuspension({ ctx, tracker, pointerAxisRef, analogRef, primaryClickRef, cameraDraggingRef, f2HeldRef, }) {
+    const reset = () => {
+        tracker.reset();
+        pointerAxisRef.current = null;
+        analogRef.current = null;
+        primaryClickRef.current = false;
+        cameraDraggingRef.current = false;
+        f2HeldRef.current = false;
+        ctx.input.publish([]);
+        ctx.input.publishPointer(null);
+        ctx.input.publishAnalog(null);
+    };
+    let active = playControlsActive(ctx);
+    if (!active)
+        reset();
+    const changed = () => {
+        const next = playControlsActive(ctx);
+        if (next === active)
+            return;
+        active = next;
+        reset();
+    };
+    const detachStack = actionContextStack(ctx).subscribe(changed);
+    const detachContext = ctx.subscribe(changed);
+    return () => { detachStack(); detachContext(); };
+}

package/dist/shellInputPublication.d.ts

@@ -0,0 +1,28 @@
+import type { ActionStateTracker } from "@jgengine/core/input/actionBindings";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { InputFrame } from "@jgengine/core/runtime/hostedGameRunner";
+import type { InputSink } from "./inputSink.js";
+type Change = "discrete" | "reset" | "analog";
+/** Observes the actual shell tracker without moving command edges or changing binding behavior. @internal */
+export declare function observableShellTracker(tracker: ActionStateTracker<string>): {
+    isDown(action: string): boolean;
+    wasPressed(action: string): boolean;
+    endFrame(): void;
+    rebind(map: import("@jgengine/core/input/actionBindings").ActionStateBindingMap<string, string>): void;
+    actions(): readonly string[];
+    handleDown(code: string): string | null;
+    handleUp(code: string): string | null;
+    reset(): void;
+    notify: (change: Change, presses?: NonNullable<InputFrame["presses"]>) => void;
+    subscribe(listener: (change: Change, presses: NonNullable<InputFrame["presses"]>) => void): () => void;
+};
+/** Publishes discrete input above Canvas, so release and failure leases survive stalled or unmounted rendering. @internal */
+export declare function attachShellInputPublication({ ctx, tracker, active, analog, pointer, sink }: {
+    ctx: GameContext;
+    tracker: ReturnType<typeof observableShellTracker>;
+    active: () => boolean;
+    analog: () => InputFrame["analog"];
+    pointer: () => InputFrame["pointer"];
+    sink: () => InputSink;
+}): () => void;
+export {};

package/dist/shellInputPublication.js

@@ -0,0 +1,49 @@
+import { heldActionsFor } from "./boundActionDispatch.js";
+let lastPressSeq = 0;
+/** Observes the actual shell tracker without moving command edges or changing binding behavior. @internal */
+export function observableShellTracker(tracker) {
+    const listeners = new Set();
+    const notify = (change, presses = []) => { for (const listener of listeners)
+        listener(change, presses); };
+    return {
+        ...tracker,
+        handleDown(code) {
+            const result = tracker.handleDown(code);
+            if (result !== null) {
+                const now = typeof performance !== "undefined" ? performance.timeOrigin + performance.now() : Date.now();
+                lastPressSeq = Math.max(now, lastPressSeq + 0.001);
+                notify("discrete", [{ action: result, seq: lastPressSeq }]);
+            }
+            return result;
+        },
+        handleUp(code) { const result = tracker.handleUp(code); notify("discrete"); return result; },
+        reset() { tracker.reset(); notify("reset"); },
+        notify,
+        subscribe(listener) { listeners.add(listener); return () => { listeners.delete(listener); }; },
+    };
+}
+const owners = new WeakMap();
+/** Publishes discrete input above Canvas, so release and failure leases survive stalled or unmounted rendering. @internal */
+export function attachShellInputPublication({ ctx, tracker, active, analog, pointer, sink }) {
+    const owner = {};
+    owners.set(ctx, owner);
+    const publish = (change, presses = []) => {
+        if (owners.get(ctx) !== owner)
+            return;
+        const enabled = active() && change !== "reset";
+        const axes = enabled ? analog() : null;
+        ctx.input.publish(enabled ? heldActionsFor(tracker, tracker.actions()) : [], enabled ? { pressed: presses.map(press => press.action) } : { reset: true });
+        ctx.input.publishPointer(enabled ? pointer() : null);
+        ctx.input.publishAnalog(axes ?? null);
+        const urgent = change !== "analog" || axes == null || Object.values(axes).every(value => value === 0);
+        sink().send({ held: ctx.input.held(), pointer: ctx.input.pointer(), analog: ctx.input.analog(), tick: ctx.sim.tick(), ...(enabled && presses.length > 0 ? { presses } : {}) }, { urgent, ...(!enabled ? { reset: true } : {}) });
+    };
+    const detach = tracker.subscribe(publish);
+    return () => {
+        detach();
+        if (owners.get(ctx) !== owner)
+            return;
+        publish("reset");
+        owners.delete(ctx);
+    };
+}

package/dist/shellPointerInput.d.ts

@@ -0,0 +1,18 @@
+import type { ActionStateTracker } from "@jgengine/core/input/actionBindings";
+import type { observableShellTracker } from "./shellInputPublication.js";
+type Pointer = {
+    pointerId: number;
+    button: number;
+};
+/** Canvas-owned physical buttons; DOM overlays never begin gameplay input. @internal */
+export declare function shellPointerInput(tracker: Pick<ActionStateTracker<string>, "handleDown" | "handleUp">, active: () => boolean): {
+    down(event: Pointer, worldTarget: boolean): void;
+    up(event: Pointer): boolean;
+    /** Native mouse chords change buttons through pointermove, including releases outside the canvas. */
+    move(event: Pointer & {
+        buttons: number;
+    }, worldTarget: boolean): void;
+    cancel(pointerId?: number): void;
+    attachReset(source: Pick<ReturnType<typeof observableShellTracker>, "subscribe">, clearGesture: () => void): () => void;
+};
+export {};

package/dist/shellPointerInput.js

@@ -0,0 +1,49 @@
+// PointerEvent.buttons uses middle=4 and right=2, unlike PointerEvent.button.
+const buttonMask = (button) => [1, 4, 2, 8, 16][button] ?? 0;
+/** Canvas-owned physical buttons; DOM overlays never begin gameplay input. @internal */
+export function shellPointerInput(tracker, active) {
+    const buttons = new Map();
+    const input = {
+        down(event, worldTarget) {
+            if (!worldTarget || !active() || buttons.has(event.button))
+                return;
+            const action = tracker.handleDown(`mouse${event.button}`);
+            buttons.set(event.button, { pointerId: event.pointerId, bound: action !== null });
+        },
+        up(event) {
+            const held = buttons.get(event.button);
+            if (held === undefined || held.pointerId !== event.pointerId)
+                return false;
+            buttons.delete(event.button);
+            tracker.handleUp(`mouse${event.button}`);
+            return held.bound;
+        },
+        /** Native mouse chords change buttons through pointermove, including releases outside the canvas. */
+        move(event, worldTarget) {
+            for (const [button, held] of buttons) {
+                if (held.pointerId === event.pointerId && (event.buttons & buttonMask(button)) === 0) {
+                    input.up({ pointerId: event.pointerId, button });
+                }
+            }
+            if (event.button >= 0 && (event.buttons & buttonMask(event.button)) !== 0)
+                input.down(event, worldTarget);
+        },
+        cancel(pointerId) {
+            for (const [button, held] of buttons) {
+                if (pointerId !== undefined && held.pointerId !== pointerId)
+                    continue;
+                buttons.delete(button);
+                tracker.handleUp(`mouse${button}`);
+            }
+        },
+        attachReset(source, clearGesture) {
+            return source.subscribe(change => {
+                if (change !== "reset")
+                    return;
+                input.cancel();
+                clearGesture();
+            });
+        },
+    };
+    return input;
+}

package/dist/structures/BuildingKitBatch.d.ts

@@ -1,8 +1,10 @@
+import type { MaterialAsset } from "@jgengine/core/material/materialAsset";
 import { type BuildingKitInstance } from "./buildingKitFit.js";
 /** Props for {@link BuildingKitBatch}: one resolved model URL and every kit instance bound to it. @internal */
 export interface BuildingKitBatchProps {
     url: string;
     instances: readonly BuildingKitInstance[];
+    materialAssets?: readonly MaterialAsset[];
 }
 /**
  * GPU-instances one kit model across every building part bound to it: the GLB loads once, its meshes
@@ -10,4 +12,4 @@ export interface BuildingKitBatchProps {
  * while the GLB loads — mount it inside a `<Suspense>` so one slow model never blanks the rest.
  * @internal
  */
-export declare function BuildingKitBatch({ url, instances }: BuildingKitBatchProps): import("react").JSX.Element;
+export declare function BuildingKitBatch({ url, instances, materialAssets }: BuildingKitBatchProps): import("react").JSX.Element;