@jgengine/shell 0.19.0 → 0.22.0

package/dist/drivers/HudOnlyDriver.js

@@ -3,12 +3,17 @@ import { dispatchBoundAction, heldActionsFor, shouldFireBoundAction } from "../b
 import { advanceBehaviors } from "@jgengine/core/scene/behaviorRuntime";
 import { playControlsActive } from "@jgengine/core/game/controlGate";
 import { devtools } from "@jgengine/core/devtools/devtools";
+import { isServerAuthoritative } from "@jgengine/core/runtime/adapter";
+import { resolveCommandSink } from "../commandSink.js";
+import { inputFramesEqual, resolveInputSink } from "../inputSink.js";
 import { EMPTY_RESERVED, NO_ACTIONS } from "../shellConstants.js";
-export function HudOnlyDriver({ ctx, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, }) {
+export function HudOnlyDriver({ ctx, multiplayer, serverIdRef, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, }) {
     const hasReportedTickError = useRef(false);
     const repeatFiredAtRef = useRef(new Map());
     const lastFrameRef = useRef(null);
     const inputActions = useMemo(() => Object.keys(playable.game.input ?? {}), [playable]);
+    const lastSentInputRef = useRef(null);
+    const serverAuthoritative = isServerAuthoritative(playable.game.multiplayer) && multiplayer !== null;
     useEffect(() => {
         let frameId;
         const tick = (now) => {
@@ -17,8 +22,19 @@ export function HudOnlyDriver({ ctx, playable, tracker, pointerAxisRef, gateRef,
             lastFrameRef.current = now;
             if (last === null)
                 return;
+            const sendInput = () => {
+                if (!serverAuthoritative || serverIdRef.current === null)
+                    return;
+                const frame = { held: ctx.input.held(), pointer: ctx.input.pointer(), analog: ctx.input.analog() };
+                if (lastSentInputRef.current !== null && inputFramesEqual(lastSentInputRef.current, frame))
+                    return;
+                lastSentInputRef.current = frame;
+                resolveInputSink({ serverAuthoritative, backend: multiplayer?.backend ?? null, serverId: serverIdRef.current }).send(frame);
+            };
             if (gateRef.current || !playControlsActive(ctx)) {
-                ctx.input.publish(heldActionsFor(tracker, NO_ACTIONS));
+                ctx.input.publish(heldActionsFor(tracker, NO_ACTIONS), { reset: true });
+                ctx.input.publishAnalog(null);
+                sendInput();
                 return;
             }
             const rawDt = (now - last) / 1000;
@@ -26,26 +42,28 @@ export function HudOnlyDriver({ ctx, playable, tracker, pointerAxisRef, gateRef,
             try {
                 let endPhase = devtools.profile.begin("time+input");
                 const dt = Math.min(rawDt, 0.05);
-                ctx.input.publish(heldActionsFor(tracker, tracker.actions()));
+                ctx.input.publish(heldActionsFor(tracker, tracker.actions()), {});
                 ctx.input.publishPointer(pointerAxisRef.current);
+                sendInput();
                 endPhase();
-                ctx.sim.advance(dt, (stepDt) => {
-                    const gameDt = ctx.time.advance(stepDt);
-                    ctx.sim.runStages("beforeMovement", stepDt);
-                    ctx.sim.runStages("afterMovement", stepDt);
-                    devtools.profile.measure("onTick", () => {
-                        playable.loop.onTick(ctx, gameDt);
+                if (!serverAuthoritative)
+                    ctx.sim.advance(dt, (stepDt, _tick, gameDt) => {
+                        ctx.input.beginStep();
+                        ctx.sim.runStages("beforeMovement", stepDt);
+                        ctx.sim.runStages("afterMovement", stepDt);
+                        devtools.profile.measure("onTick", () => {
+                            playable.loop.onTick(ctx, gameDt);
+                        });
+                        advanceBehaviors(ctx, gameDt);
+                        ctx.sim.runStages("afterTick", stepDt);
                     });
-                    advanceBehaviors(ctx, gameDt);
-                    ctx.sim.runStages("afterTick", stepDt);
-                });
                 endPhase = devtools.profile.begin("actions");
                 const nowMs = performance.now();
                 for (const action of inputActions) {
                     if (!shouldFireBoundAction(tracker, action, playable.game.input, repeatFiredAtRef.current, nowMs))
                         continue;
                     repeatFiredAtRef.current.set(action, nowMs);
-                    dispatchBoundAction(ctx, action, 0, 0, { yaw: 0, pitch: 0 }, EMPTY_RESERVED);
+                    dispatchBoundAction(ctx, action, 0, 0, { yaw: 0, pitch: 0 }, EMPTY_RESERVED, resolveCommandSink(ctx, { serverAuthoritative, backend: multiplayer?.backend ?? null, serverId: serverIdRef.current }));
                 }
                 tracker.endFrame();
                 endPhase();
@@ -60,6 +78,6 @@ export function HudOnlyDriver({ ctx, playable, tracker, pointerAxisRef, gateRef,
         };
         frameId = requestAnimationFrame(tick);
         return () => cancelAnimationFrame(frameId);
-    }, [ctx, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, inputActions]);
+    }, [ctx, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, inputActions, multiplayer, serverIdRef, serverAuthoritative]);
     return null;
 }

package/dist/environment/EnvironmentScene.js

@@ -1,7 +1,8 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef } from "react";
 import { useFrame } from "@react-three/fiber";
-import { useTexture } from "@react-three/drei";
+import { PresentationAssetBoundary } from "../presentationRecovery.js";
+import { PresentationRecoveredDraw, useRecoverableTexture } from "../presentationRecovery3d.js";
 import * as THREE from "three";
 import { useGameContext } from "@jgengine/react/provider";
 import { resolveBuildingPalette } from "@jgengine/core/world/buildings";
@@ -9,6 +10,8 @@ import { resolveStructureBuildings } from "@jgengine/core/world/environmentSumma
 import { findRoadJunctions } from "@jgengine/core/world/streets";
 import { createTerrainPaletteSampler, resolveEnvironmentField, resolveTerrainDetail, resolveTerrainPalette, } from "@jgengine/core/world/terrain";
 import { useDisposable } from "../render/useDisposable.js";
+import { editableTerrainFromSnapshot } from "@jgengine/core/world/terraform";
+import { createTerrainPaintColorSampler } from "../terrain/terrainPaintColor.js";
 import { GroundPad } from "./GroundPad.js";
 import { RoadJunctions } from "./RoadJunctions.js";
 import { buildAuthoredRoadNetwork, RoadRibbons } from "./RoadRibbons.js";
@@ -20,14 +23,13 @@ import { createTerrainDetailMaterial } from "../terrain/terrainDetailMaterial.js
 import { Ocean } from "../water/Ocean.js";
 import { RainField } from "../weather/RainField.js";
 import { SnowField } from "../weather/SnowField.js";
-import { WeatherUniformProvider } from "../weather/weatherUniforms.js";
 function TexturedTerrainGround({ detail, layout, }) {
     const maps = detail.material.maps;
-    const textures = useTexture({
+    const textures = useRecoverableTexture({
         color: maps.color,
         normal: maps.normal,
-        roughness: maps.roughness,
-        ao: maps.ao,
+        ...(maps.roughness !== undefined ? { roughness: maps.roughness } : {}),
+        ...(maps.ao !== undefined ? { ao: maps.ao } : {}),
     });
     useEffect(() => {
         textures.color.colorSpace = THREE.SRGBColorSpace;
@@ -38,9 +40,10 @@ function TexturedTerrainGround({ detail, layout, }) {
         }
     }, [textures]);
     const material = useDisposable(() => createTerrainDetailMaterial(detail, textures).material, [detail, textures]);
-    return (_jsx(CarvedTerrain, { field: layout.field, size: layout.size, segments: layout.segments, colors: layout.colors, heightRange: layout.heightRange, paletteAt: layout.paletteAt, center: layout.center, roughness: 0.94, surfaceMaterial: material }));
+    return (_jsxs(_Fragment, { children: [_jsx(PresentationRecoveredDraw, {}), _jsx(CarvedTerrain, { field: layout.field, size: layout.size, segments: layout.segments, colors: layout.colors, heightRange: layout.heightRange, paletteAt: layout.paletteAt, paintColorAt: layout.paintColorAt, center: layout.center, roughness: 0.94, surfaceMaterial: material })] }));
 }
-function TerrainGround({ terrain, field, center, }) {
+function TerrainGround({ terrain, field, center, sculpt, }) {
+    const paintColorAt = useMemo(() => sculpt === undefined ? undefined : createTerrainPaintColorSampler(editableTerrainFromSnapshot(sculpt)), [sculpt]);
     const palette = useMemo(() => resolveTerrainPalette(terrain), [terrain]);
     const paletteAt = useMemo(() => {
         const hasRegions = terrain.materialRegions !== undefined && terrain.materialRegions.length > 0;
@@ -69,9 +72,9 @@ function TerrainGround({ terrain, field, center, }) {
         : createTerrainDetailMaterial(resolvedDetail).material, [resolvedDetail]);
     useEffect(() => () => proceduralMaterial?.dispose(), [proceduralMaterial]);
     if (resolvedDetail?.material !== undefined) {
-        return (_jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, center } }));
+        return (_jsx(PresentationAssetBoundary, { children: _jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, paintColorAt, center } }) }));
     }
-    return (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, center: center, roughness: 0.94, surfaceMaterial: proceduralMaterial }));
+    return (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, paintColorAt: paintColorAt, center: center, roughness: 0.94, surfaceMaterial: proceduralMaterial }));
 }
 function areaCenter(area) {
     return area.position ?? [0, 0];
@@ -88,8 +91,8 @@ function Vegetation({ grass, field, groundColor, }) {
     return (_jsx("group", { position: [cx, 0, cz], children: _jsx(GrassField, { area: area, count: Math.max(1500, Math.min(250000, Math.ceil(grass.density * grass.area.w * grass.area.d))), density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, bladeBend: grass.bladeBend, tuftRadius: grass.tuftRadius, colorVariation: grass.colorVariation, normalLift: grass.normalLift, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, colorGround: groundColor, wind: wind, edgeFeather: Math.min(8, Math.max(1.5, Math.min(grass.area.w, grass.area.d) * 0.12)), frustumCulled: true }) }));
 }
 /** Terrain color under a grass patch center — so blade roots blend into the ground they stand on. */
-function vegetationGroundColor(terrain, field, grass) {
-    const sampler = terrainGroundColorSampler(terrain, field);
+function vegetationGroundColor(terrain, field, grass, sculpt) {
+    const sampler = terrainGroundColorSampler(terrain, field, sculpt);
     if (sampler === undefined)
         return undefined;
     const [cx, cz] = areaCenter(grass.area);
@@ -99,14 +102,15 @@ function weatherVolume(area) {
     return [area.w, area.h ?? 60, area.d];
 }
 function Precipitation({ weather }) {
+    const ctx = useGameContext();
     const [cx, cz] = areaCenter(weather.area);
     if (weather.kind === "rain") {
-        return (_jsx("group", { position: [cx, 0, cz], children: _jsx(RainField, { density: weather.density, speed: weather.speed, length: weather.dropLength, width: weather.width, opacity: weather.opacity, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
+        return (_jsx("group", { position: [cx, 0, cz], children: _jsx(RainField, { timeSeconds: ctx.time.now, density: weather.density, speed: weather.speed, length: weather.dropLength, width: weather.width, opacity: weather.opacity, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
     }
-    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(SnowField, { density: weather.density, speed: weather.speed, size: weather.flakeSize, sway: weather.drift, opacity: weather.opacity, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
+    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(SnowField, { timeSeconds: ctx.time.now, density: weather.density, speed: weather.speed, size: weather.flakeSize, sway: weather.drift, opacity: weather.opacity, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
 }
 function Weather({ weather }) {
-    return (_jsx(WeatherUniformProvider, { children: weather.map((entry, index) => (_jsx(Precipitation, { weather: entry, index: index }, `${entry.kind}-${index}`))) }));
+    return (_jsx(_Fragment, { children: weather.map((entry, index) => (_jsx(Precipitation, { weather: entry, index: index }, `${entry.kind}-${index}`))) }));
 }
 function oceanConfig(ocean) {
     return {
@@ -159,5 +163,5 @@ export function EnvironmentScene({ feature }) {
     const roads = feature.roads ?? [];
     const junctions = useMemo(() => findRoadJunctions(roads), [roads]);
     const roadNetwork = useMemo(() => buildAuthoredRoadNetwork(roads, junctions, (x, z) => field.sampleHeight(x, z)), [roads, junctions, field]);
-    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin }, `island-${index}`))), water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), roads.map((entry, index) => (_jsx(RoadRibbons, { road: entry, field: field, paths: roadNetwork.roadPaths[index] ?? [] }, `road-${index}`))), _jsx(RoadJunctions, { surfaces: roadNetwork.junctionSurfaces, junctions: junctions, field: field }), structures.map((entry, index) => (_jsx(Structures, { structures: entry, field: field }, `structures-${index}`))), pads.map((entry, index) => (_jsx(GroundPad, { pad: entry, field: field }, `pad-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field, groundColor: vegetationGroundColor(feature.terrain, field, grass) }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
+    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field, sculpt: feature.sculpt }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin, sculpt: feature.sculpt }, `island-${index}`))), water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), roads.map((entry, index) => (_jsx(RoadRibbons, { road: entry, field: field, paths: roadNetwork.roadPaths[index] ?? [] }, `road-${index}`))), _jsx(RoadJunctions, { surfaces: roadNetwork.junctionSurfaces, junctions: junctions, field: field }), structures.map((entry, index) => (_jsx(Structures, { structures: entry, field: field }, `structures-${index}`))), pads.map((entry, index) => (_jsx(GroundPad, { pad: entry, field: field }, `pad-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field, groundColor: vegetationGroundColor(feature.terrain, field, grass, feature.sculpt) }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
 }

package/dist/environment/terrainGroundColor.d.ts

@@ -1,9 +1,10 @@
 import type { TerrainEnvironmentDescriptor } from "@jgengine/core/world/features";
 import { type TerrainField } from "@jgengine/core/world/terrain";
+import { type TerraformSnapshot } from "@jgengine/core/world/terraform";
 /**
- * Terrain surface color at a world XZ — the palette low/high lerped by the sampled ground height,
- * mirroring how `CarvedTerrain` shades its vertices. The seam that lets everything planted on the
- * ground (grass roots, soil-patch borders) blend into the exact color it stands on.
+ * Terrain base color at a world XZ — authored paint first, otherwise the regional palette lerped
+ * by ground height. Grass roots and soil-patch borders share the painted color with ground vertices.
+ * Descriptor surface mottling and fragment detail are presentation overlays, not sampled here.
  * @internal
  */
-export declare function terrainGroundColorSampler(terrain: Omit<TerrainEnvironmentDescriptor, "kind"> | undefined, field: TerrainField): ((x: number, z: number) => string) | undefined;
+export declare function terrainGroundColorSampler(terrain: Omit<TerrainEnvironmentDescriptor, "kind"> | undefined, field: TerrainField, sculpt?: TerraformSnapshot): ((x: number, z: number) => string) | undefined;

package/dist/environment/terrainGroundColor.js

@@ -1,21 +1,32 @@
 import * as THREE from "three";
-import { resolveTerrainPalette } from "@jgengine/core/world/terrain";
+import { createTerrainPaletteSampler, resolveTerrainPalette } from "@jgengine/core/world/terrain";
+import { editableTerrainFromSnapshot } from "@jgengine/core/world/terraform";
+import { createTerrainPaintColorSampler } from "../terrain/terrainPaintColor.js";
 /**
- * Terrain surface color at a world XZ — the palette low/high lerped by the sampled ground height,
- * mirroring how `CarvedTerrain` shades its vertices. The seam that lets everything planted on the
- * ground (grass roots, soil-patch borders) blend into the exact color it stands on.
+ * Terrain base color at a world XZ — authored paint first, otherwise the regional palette lerped
+ * by ground height. Grass roots and soil-patch borders share the painted color with ground vertices.
+ * Descriptor surface mottling and fragment detail are presentation overlays, not sampled here.
  * @internal
  */
-export function terrainGroundColorSampler(terrain, field) {
-    if (terrain === undefined)
+export function terrainGroundColorSampler(terrain, field, sculpt) {
+    if (terrain === undefined && sculpt === undefined)
         return undefined;
     const palette = resolveTerrainPalette(terrain);
+    const paletteAt = terrain === undefined ? undefined : createTerrainPaletteSampler(terrain);
+    const paintColorAt = sculpt === undefined ? undefined : createTerrainPaintColorSampler(editableTerrainFromSnapshot(sculpt));
     const low = new THREE.Color(palette.low);
     const high = new THREE.Color(palette.high);
-    const base = terrain.baseHeight ?? 0;
-    const swing = terrain.height * 1.2;
+    const base = terrain?.baseHeight ?? 0;
+    const swing = (terrain?.height ?? 0) * 1.2;
     const scratch = new THREE.Color();
     return (x, z) => {
+        if (paintColorAt?.(x, z, scratch))
+            return `#${scratch.getHexString()}`;
+        const regional = paletteAt?.(x, z);
+        if (regional !== undefined) {
+            low.set(regional.low);
+            high.set(regional.high);
+        }
         const t = swing <= 0 ? 0.5 : THREE.MathUtils.clamp((field.sampleHeight(x, z) - (base - swing)) / (swing * 2), 0, 1);
         return `#${scratch.copy(low).lerp(high, t).getHexString()}`;
     };

package/dist/inputSink.d.ts

@@ -2,17 +2,17 @@ import { type InputFrame } from "@jgengine/core/runtime/hostedGameRunner";
 import type { LiveGameBackend } from "@jgengine/core/runtime/transport";
 /** Where the local player's per-frame input goes: discarded in single-player, sent to the authoritative host under `authority: "server"`. */
 export interface InputSink {
-    send(frame: InputFrame): void;
+    send(frame: InputFrame, options?: {
+        urgent?: boolean;
+        reset?: boolean;
+    }): void;
 }
 /** Discards input — the single-player / client-authoritative default, where the client integrates movement itself.
  * @internal
  */
 export declare function noopInputSink(): InputSink;
-/**
- * Sends each frame's input to the authoritative host over the transport, reusing the `runCommand` path via
- * {@link INPUT_COMMAND}. Sends are sequenced one-in-flight-at-a-time per `serverId` and stamped with a monotonic
- * seq: a frame sent while one is already in flight replaces the pending frame rather than racing it, so the
- * latest intent always wins and a stale frame can never resolve after (and overwrite) a newer one.
+/** Coalesces continuous frames. Discrete release/reset intents bypass a pending ACK;
+ * the host's monotonic sequence admission rejects any older input arriving afterwards.
  * @internal
  */
 export declare function remoteInputSink(backend: Pick<LiveGameBackend, "transport">, serverId: string): InputSink;

package/dist/inputSink.js

@@ -5,56 +5,91 @@ import { INPUT_COMMAND } from "@jgengine/core/runtime/hostedGameRunner";
 export function noopInputSink() {
     return { send() { } };
 }
-const remoteInputSources = new Map();
-function remoteInputSourceFor(serverId) {
-    let source = remoteInputSources.get(serverId);
+const remoteInputSources = new WeakMap();
+let lastInputSeq = 0;
+function remoteInputSourceFor(backend, serverId) {
+    let sources = remoteInputSources.get(backend.transport);
+    if (sources === undefined) {
+        sources = new Map();
+        remoteInputSources.set(backend.transport, sources);
+    }
+    let source = sources.get(serverId);
     if (source === undefined) {
-        source = { pending: null, inFlight: false };
-        remoteInputSources.set(serverId, source);
+        source = { pending: null, inFlight: null, latest: null, presses: new Map() };
+        sources.set(serverId, source);
     }
     return source;
 }
+// Use the browser time origin so a full reload stays ahead of the previous client.
+// The local high-water mark also preserves release ordering if its clock regresses.
 function monotonicInputSeq() {
-    return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+    const now = typeof performance !== "undefined" ? performance.timeOrigin + performance.now() : Date.now();
+    return lastInputSeq = Math.max(now, lastInputSeq + 0.001);
 }
 function pumpRemoteInput(backend, serverId, source) {
-    if (source.inFlight)
+    if (source.inFlight !== null)
         return;
     const frame = source.pending;
     if (frame === null) {
-        remoteInputSources.delete(serverId);
+        if (source.presses.size === 0)
+            remoteInputSources.get(backend.transport)?.delete(serverId);
         return;
     }
     source.pending = null;
-    source.inFlight = true;
+    const owner = {};
+    source.inFlight = owner;
+    const presses = [...source.presses.values()].map(press => ({ ...press }));
     const seq = monotonicInputSeq();
+    // Live clients and the joined host have independent simulation clocks. The host
+    // stamps receipt on its next tick; explicit ticks remain supported by replay.
+    const { tick: _clientTick, presses: _framePresses, ...intent } = frame;
     void backend.transport
-        .runCommand({ serverId, command: INPUT_COMMAND, input: { ...frame, seq } })
+        .runCommand({ serverId, command: INPUT_COMMAND, input: { ...intent, ...(presses.length > 0 ? { presses } : {}), seq } })
         .then((result) => {
-        if (!result.ok) {
+        if (result.ok)
+            for (const press of presses)
+                source.presses.delete(press.seq);
+        if (!result.ok)
             console.warn(`[jgengine:input] frame seq=${seq} to server "${serverId}" rejected: ${result.reason}`);
-        }
     })
         .catch((error) => {
         console.warn(`[jgengine:input] frame seq=${seq} to server "${serverId}" failed to send`, error);
     })
         .finally(() => {
-        source.inFlight = false;
+        // An urgent discrete intent supersedes this flight. Its old completion must not
+        // release the replacement's ACK gate or replay the superseded pending frame.
+        if (source.inFlight !== owner)
+            return;
+        source.inFlight = null;
         pumpRemoteInput(backend, serverId, source);
     });
 }
-/**
- * Sends each frame's input to the authoritative host over the transport, reusing the `runCommand` path via
- * {@link INPUT_COMMAND}. Sends are sequenced one-in-flight-at-a-time per `serverId` and stamped with a monotonic
- * seq: a frame sent while one is already in flight replaces the pending frame rather than racing it, so the
- * latest intent always wins and a stale frame can never resolve after (and overwrite) a newer one.
+/** Coalesces continuous frames. Discrete release/reset intents bypass a pending ACK;
+ * the host's monotonic sequence admission rejects any older input arriving afterwards.
  * @internal
  */
 export function remoteInputSink(backend, serverId) {
     return {
-        send(frame) {
-            const source = remoteInputSourceFor(serverId);
-            source.pending = frame;
+        send(frame, options) {
+            const source = remoteInputSourceFor(backend, serverId);
+            if (options?.reset)
+                source.presses.clear();
+            for (const press of frame.presses ?? [])
+                source.presses.set(press.seq, { ...press });
+            // A reset must overtake an identical neutral release that still carries an
+            // unacknowledged press. Intent equality alone does not describe that flight.
+            if (!options?.reset && source.latest !== null && inputFramesEqual(source.latest, frame) && source.presses.size === 0)
+                return;
+            const snapshot = {
+                ...frame, held: [...frame.held],
+                ...(frame.presses === undefined ? {} : { presses: frame.presses.map(press => ({ ...press })) }),
+                pointer: frame.pointer === null ? null : { ...frame.pointer },
+                ...(frame.analog === undefined ? {} : { analog: frame.analog === null ? null : { ...frame.analog } }),
+            };
+            source.latest = snapshot;
+            source.pending = snapshot;
+            if (options?.urgent)
+                source.inFlight = null;
             pumpRemoteInput(backend, serverId, source);
         },
     };
@@ -72,6 +107,10 @@ export function resolveInputSink(opts) {
  * @internal
  */
 export function inputFramesEqual(a, b) {
+    const ap = a.presses ?? [];
+    const bp = b.presses ?? [];
+    if (ap.length !== bp.length || ap.some((press, index) => press.seq !== bp[index].seq || press.action !== bp[index].action))
+        return false;
     if (a.held.length !== b.held.length)
         return false;
     for (let i = 0; i < a.held.length; i++)

package/dist/lazyShell3dPresentation.d.ts

@@ -0,0 +1,9 @@
+import { type ComponentProps } from "react";
+import type { Shell3dPresentation } from "./Shell3dPresentation.js";
+type Presentation = typeof Shell3dPresentation;
+type Props = ComponentProps<Presentation> & {
+    onPresentationReveal?: () => void;
+};
+/** Loads the normal 3D implementation only for a 3D presentation. @internal */
+export declare function LazyShell3dPresentation({ onPresentationReveal, ...props }: Props): import("react").JSX.Element;
+export {};

package/dist/lazyShell3dPresentation.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { lazy, Suspense, useLayoutEffect, useState } from "react";
+import { suspendPlayControls } from "@jgengine/core/game/controlGate";
+import { markPresentationCodeLoadFailure } from "./presentationRecovery.js";
+let loadedPresentation;
+function getPresentation() {
+    return loadedPresentation ??= lazy(() => import("./Shell3dPresentation.js").then((module) => ({ default: module.Shell3dPresentation }), (error) => {
+        throw markPresentationCodeLoadFailure(error);
+    }));
+}
+function LoadingPresentation({ ctx }) {
+    useLayoutEffect(() => suspendPlayControls(ctx), [ctx]);
+    return (_jsx("div", { role: "status", "aria-live": "polite", "data-shell-code-loading": true, style: { display: "grid", placeItems: "center", width: "100%", height: "100%", minHeight: 160, background: "#0f172a", color: "#e2e8f0", fontFamily: "ui-sans-serif, system-ui, sans-serif" }, children: "Loading game view\u2026" }));
+}
+function PresentationReveal({ onReveal }) {
+    // React repeats layout effects when a suspended tree becomes visible again.
+    useLayoutEffect(() => { onReveal?.(); });
+    return null;
+}
+/** Loads the normal 3D implementation only for a 3D presentation. @internal */
+export function LazyShell3dPresentation({ onPresentationReveal, ...props }) {
+    const [Presentation] = useState(getPresentation);
+    return (_jsxs(Suspense, { fallback: _jsx(LoadingPresentation, { ctx: props.ctx }), children: [_jsx(Presentation, { ...props }), _jsx(PresentationReveal, { onReveal: onPresentationReveal })] }));
+}

package/dist/materialOverride.d.ts

@@ -4,6 +4,8 @@ export interface MaterialOverrideOptions {
     clone?: boolean;
     /** Loaded PBR textures matching `ModelMaterialOverride.maps`' roles, applied onto each standard or physical material alongside the tint override. The caller (a React component, via `useTexture`) owns loading; this function never fetches a URL. */
     textures?: MaterialOverrideTextures;
+    /** Records material replacements for the caller's resource owner. */
+    ownMaterial?: (material: THREE.Material) => void;
 }
 /** Loaded PBR textures for `applyMaterialOverride`'s `textures` option — matches `ModelMaterialMaps`' roles. */
 export interface MaterialOverrideTextures {
@@ -14,6 +16,46 @@ export interface MaterialOverrideTextures {
     metalness?: THREE.Texture;
     emissive?: THREE.Texture;
     height?: THREE.Texture;
+    alpha?: THREE.Texture;
+    sheenColor?: THREE.Texture;
+    sheenRoughness?: THREE.Texture;
+    anisotropy?: THREE.Texture;
+    clearcoat?: THREE.Texture;
+    clearcoatRoughness?: THREE.Texture;
+    clearcoatNormal?: THREE.Texture;
+    specularIntensity?: THREE.Texture;
+    specularColor?: THREE.Texture;
+    transmission?: THREE.Texture;
+    thickness?: THREE.Texture;
+    iridescence?: THREE.Texture;
+    iridescenceThickness?: THREE.Texture;
 }
+/** Physical texture roles mapped to the pinned Three renderer's native properties. @internal */
+export declare const MATERIAL_TEXTURE_PROPERTIES: {
+    readonly color: "map";
+    readonly normal: "normalMap";
+    readonly roughness: "roughnessMap";
+    readonly ao: "aoMap";
+    readonly metalness: "metalnessMap";
+    readonly emissive: "emissiveMap";
+    readonly height: "displacementMap";
+    readonly alpha: "alphaMap";
+    readonly sheenColor: "sheenColorMap";
+    readonly sheenRoughness: "sheenRoughnessMap";
+    readonly anisotropy: "anisotropyMap";
+    readonly clearcoat: "clearcoatMap";
+    readonly clearcoatRoughness: "clearcoatRoughnessMap";
+    readonly clearcoatNormal: "clearcoatNormalMap";
+    readonly specularIntensity: "specularIntensityMap";
+    readonly specularColor: "specularColorMap";
+    readonly transmission: "transmissionMap";
+    readonly thickness: "thicknessMap";
+    readonly iridescence: "iridescenceMap";
+    readonly iridescenceThickness: "iridescenceThicknessMap";
+};
+/** Whether authored settings require a physical shader; ordinary PBR stays standard. @internal */
+export declare function requiresPhysicalMaterial(override: ModelMaterialOverride, textures?: MaterialOverrideTextures): boolean;
 /** @internal */
 export declare function applyMaterialOverride(root: THREE.Object3D, override: ModelMaterialOverride, options?: MaterialOverrideOptions): void;
+/** Apply the shared override contract to one material. @internal */
+export declare function applyMaterialOverrideToMaterial(material: THREE.Material, override: ModelMaterialOverride, clone: boolean, textures: MaterialOverrideTextures | undefined): THREE.Material;