@jgengine/shell 0.17.0 → 0.18.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-The lockstep game SDK set is `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`
+The lockstep game SDK set is `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets}`
 (this file’s 0.x.y releases). The CLI package `jgengine` and `@jgengine/github` use
 **separate** version lines and may lag. Format follows [Keep a Changelog](https://keepachangelog.com);
 each release **leads with a Migrate block** — the concrete steps to move a game
@@ -17,6 +17,13 @@ between (`--json` for structured output).
 
 ## [Unreleased]
 
+### Fixed
+
+- Separate SDK publication validation from external Games quality checks while retaining the full local and main-branch gates.
+
+- Correct foot-IK endpoint recomputation after hip rotation; verify reachable targets and clamping without changing bone lengths.
+- Restore release CI prerequisites and make catalog-loader tests independent of the external Games checkout.
+
 <!--
 Every PR that changes `packages/*/src` records its consumer-facing change here, so
 the next release's notes are complete by construction. Add a bullet under the right
@@ -26,14 +33,130 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.18.1
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.18.1`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.15.1`; `@jgengine/github` is `0.5.1`.
+- Declare `topology: "shared"` on runtime definitions. Shared Convex hosts migrate the bounded legacy roster into indexed membership and per-player session rows; use `getServerCapacity` for stable lobby subscriptions.
+- Put every command's read scope on its definition. Omitted scopes now load the actor and no chunks; explicitly request whole-world reads only where needed. Trusted host mutations can compose writes through `helpers.runCommand`.
+- Handle typed join outcomes (`ok` and `reason`) or use `useServerSession` and `JoinGate`. Pass runtimes to `jgengineCronSpecs`; tick registration requires an actual tick hook.
+- Declare currency precision with `decimals` and remove game-side cent conversions. Public amounts stay in major units and wallet writes round through integer minor units.
+- Replace custom presence, chat, territory and tick batching with `createWorldPresenceStore`, chat helpers, chunk territory, and `forEachOnlinePlayer`. Legacy claim backfills must finish before removing their old schema.
+
+### Added
+
+- Indexed shared membership and capacity rows, bounded neighborhood poses with 100 ms server/client gates, durable rate limits, authenticated diagnostics and bounded retention.
+- Territory footprint planning and atomic placement claims, chat validation and headless chat/join/territory surfaces, elapsed accrual, safe quantities, and player-profile reset through the initializer.
+- An explicit `--patch` release option.
+
+### Added
+
+- Added smooth interpolation for remote presence player poses.
+- WS ping/pong messages and client RTT sampling on the backend object.
+- Added skin-backed HUD chrome variables, font loading, and the procedural `HudSkinPreview` fixture.
+
+- Core gamepad snapshot model, deadzone/curve resolver, and controller glyph labels.
+- Shell gamepad source polls connected pads, merges analog actions, supports synthetic `?gamepad=1` input, and exposes `ctx.input.rumble`.
+- Core action context stacks layer gameplay, menus, and passthrough overlays with snapshot/restore; shell action tracking now respects the active context.
+- Shell audio now supports listener orientation and per-sound Web Audio panners. `setListenerPose` accepts `{ position, forward, up }`; bare positions remain supported for one release.
+- Core perception tracks deterministic sight, hearing, occlusion, and bounded observation memory for AI.
+- `syncWorldColliders` now keeps terrain and static object colliders synchronized with a physics backend.
+- Core decision graphs provide deterministic selector, sequence, condition, action, and utility runtimes with snapshot/restore.
+- Core behavior descriptors can run registered decision graphs at the interest-scheduler cadence.
+- Core navigation meshes provide deterministic polygon routing, off-mesh links, closest-point queries, and nav raycasts.
+- WS sessions now issue resume tickets and retain disconnected memberships for a 15-second grace window, allowing reconnects to rejoin without replacing player state.
+- Shell entity sprites can play atlas-backed sprite clips while preserving raw texture sprites.
+- Tilemap layers can render atlas-backed textured tiles as one instanced quad mesh with parallax.
+- Core pixel-perfect orthographic frustum and pixel-grid camera snapping are available to shell cameras.
+- Core sprite atlas adapters and deterministic 2D sprite clip playback primitives.
+- `src/art-direction.md` scaffold and `check-art-direction` gate for created games.
+- Host-authoritative shell sessions now expose each accepted world frame to the local prediction buffer, reconciling and snapping the possessed pose only when drift exceeds its threshold.
+- Shared GLTF loader configuration for Draco and KTX2-compressed assets, with CDN defaults and renderer capability detection.
+- Material map overrides now support metalness, emissive, and height maps on standard and physical materials.
+- Presentation and editor documents now accept gradient, HDRI/EXR, and cube-map environment sources.
+- Authored `light` markers now feed bounded point/spot punctual lights with an eight-light default budget and editor warning.
+- Graphics profiles now resolve per-tier render scale, shadow budgets, culling distance, particles, cascades, and post stages; games can override them with `defineGame({ graphics })`.
+- `defineGame({ physics: { backend } })` now adopts a capsule character controller for shell/headless movement and registers the backend simulation after movement, including floor collision and step-up behavior.
+- Added the `physics-probe` dev scene for Rapier crate, ragdoll, and vehicle motion.
+- Assets now expose import-spec validation and magic-byte classification for supported source files.
+- Hosted WS sessions now support spectator joins, viewer roles, throttled low-priority snapshot modules, and default command rate limits.
+- `@jgengine/navbake` bakes deterministic navigation meshes and editor documents can store named bake data.
+- Core tactical queries derive cover points and score bounded candidate positions.
+- Added createSnapshotBuffer for delayed snapshot interpolation.
+
 ### Migrate
 
+- `AudioEngine.setListenerPose` now accepts `{ position, forward, up }`. Bare `Vec3` positions remain compatible for one release and use forward `[0, 0, -1]` with up `[0, 1, 0]`.
+- **Hosted world stores are asynchronous.** Implement `HostedWorldStore.load()` and `save()` as `Promise`-returning methods and construct persisted sessions with `createHostedWorldSessionAsync`; synchronous tests can keep using `memoryWorldStore`.
+- **Look presets now default to `neutral`.** Games that relied on the previous implicit cinematic
+  sky/post stack should set `look: "photoreal"` (or keep `look: "cinematic"`) explicitly.
+
+- **`ServerTickPlan.due` is `{ id, runs }[]` instead of a repeated id list.** `planServerTick` repeated a system id once per missed interval, and the obvious way to consume that — `due.includes(id)` or a `Set` — ran the system once while the returned anchor had already advanced by every repeat, silently dropping the catch-up work. A host now reads `runs` (or `tickRunCount(plan, id)`) and loops that many times.
+- **`CommandDef.validate` / `CommandDef.apply` take a fourth argument, `nowMs`.** Existing implementations that ignore it are unaffected. Commands that took a `now` in their `input` should read this instead — the client supplied the old one.
+
 ### Changed
 
+- Hosted game runner queues authoritative inputs by simulation tick and applies the in-force frame each fixed step.
+- Create scaffolds now use a 60 Hz simulation with interpolation enabled by default.
+
+- Rigged `ModelConfig` entries can opt into shell foot IK with named thigh/shin/foot bones; the driver raycasts the shared scene terrain, solves each chain, and fades corrections while airborne.
+
+- Animation graph clips may carry root-bone position tracks; states with `rootMotion: true` return the sampled displacement and the shell applies it to the entity while restoring the root bone's bind translation.
+
+- Added renderer-free two-bone, FABRIK, and look-at inverse-kinematics solvers to `@jgengine/core`.
+
+- Shell model animation now routes states and one-shots through the shared animation graph runtime.
+
+- CI now clones the external games repository with `GAMES_CLONE_TOKEN` and runs the game shape, content, front-end, art-direction, and feel gates against it; those gates fail loudly in CI when the checkout is missing while remaining no-ops locally.
+
+- `jgengine create` now accepts `--player`, `--ground`, and `--scene` so generated games can choose their model, terrain ground, and empty or starter scene.
+
+- **Directional shadow frustum config actually reaches the GPU.** `shadowCameraSize` on a single (non-cascaded) shadow light was silently inert: the shell wrote the bounds through R3F pierced props and nothing refreshed the shadow camera's projection matrix, so three rendered depth with its default ~10-unit box at the world origin — the reason no open-world game had cast shadows away from spawn. The shell now syncs the projection (and reallocates the shadow map when `shadowMapSize` changes). `bloom.threshold`'s doc also now states it measures raw HDR before the exposure stage.
+- **CSM (`cascades > 1`) no longer over-lights streamed meshes or clobbers material shaders.** Cascade scoping is injected per material, but the scan ran every 30 frames, so a model that streamed in rendered lit by every cascade light at once (a cascades× sun) until the next scan — a sub-second flash on desktop, the whole shot on capture rigs. The scan now runs every frame behind a WeakSet, and `setupMaterial` chains with a material's own `onBeforeCompile` (rim light, detail maps) instead of replacing it.
+
+- **The host's wall clock reaches the runtime hooks.** `RuntimeInitContext` (so `onInit`, `onNewPlayer`, and `onTick` alike) carries `nowMs`, the host timestamp for that call. Anything keyed to real time — a UTC date rollover, a `lastTickAt` anchor read by non-tick code, an RNG seed or `createdAt` stamp — reads it rather than accumulating `dtSeconds` against an epoch persisted in the snapshot, which drifts by whatever the tick loses to stalls and `maxCatchUp` clamping. `GameRuntime.hydrate` takes an optional `nowMs`; `tick`, `joinPlayer`, and `runCommand` take an optional trailing `nowMs`. All default to `Date.now()`, and the shipped WS and Convex hosts pass the timestamp they already computed to plan the tick.
+- **Imported models cast and receive shadows.** `cloneModelScene` never set `castShadow`/`receiveShadow` on a GLB's meshes (only the magenta fallback box had them), so every catalog model in every game rendered shadowless however the lights were configured. Cloned models now default to `ModelConfig.shadows: "both"`; set `"cast"`, `"receive"`, or `"none"` per model (foliage cards, decals, viewmodels).
+- **`jgengine create` installs `game-design` and `jgengine-ui` by default.** The minimal skill set was intake, editor, and verify, so a real project never saw the greenfield design contract or the UI art-direction template unless someone ran `jgengine skills --all`; `MINIMAL_GAME_SKILLS` now carries both.
+
 ### Added
 
+- **Host-authoritative world replication over WS.** Hosted sessions expose revision-cursor pulls, so server subscribers receive compact world diffs and automatically recover with a fresh baseline after missed revisions; viewer-specific projections still receive per-viewer baselines.
+- **Animation graph — `ModelAnimationConfig.graph` and `@jgengine/core/anim/animGraph`.** A serializable, layered animation state machine: `clip`, `blend1D`, and `blend2D` states, transitions as data (parameter comparisons, consumed triggers, exit times, crossfade durations), masked and additive layers, and clip events. `createAnimGraphRuntime` is headless and owns every clip's playback time and weight, so the shell's mixer only seeks and weights actions (`useModelAnimation` takes the graph path when `graph` is set) and a headless host or test advances the same graph without three.js. The shell feeds the entity's smoothed ground speed as `speed`, merges parameters from the entity blackboard key `ANIM_PARAMS_KEY`, arms triggers from `entity.animation` / `combat.hitReaction` / `entity.died`, and emits the new `animation.event` for clip events (foot plants, hit frames). `locomotionGraph()` builds the previous idle/walk/run plus one-shot behavior as one authored graph.
+- **`PhysicsBackend` — one interface over interchangeable rigid-body solvers.** `@jgengine/core/physics/physicsBackend` defines bodies (`BodyDesc` with a box / sphere / capsule / convex / trimesh / heightfield shape union, quaternion rotation, angular velocity, layers and mask, CCD flag), joints, `raycast`, `shapecast`, `overlap`, contact events, and `snapshot`/`restore` with stable handles; `capabilities` says what a backend really does. `createPhysicsWorldBackend` puts the zero-dependency `PhysicsWorld` behind it (translation-only, non-box shapes collide as their bounding box, warned once), and `runPhysicsBackendConformance` is the behavioral contract any adapter runs. `createCharacterController` (`@jgengine/core/movement/characterController`) is the first consumer: a capsule collide-and-slide controller with step-up, slope limit, ceiling test, crouch with headroom check, ground snapping, and moving-platform carry, pure over any backend and retunable during play.
+- **Fixed-step simulation with render interpolation — `defineGame({ simulation: { hz } })` and `ctx.sim`.** Every driver (shell frame, HUD-only, headless runner, authoritative host) now steps through one `SimLoop` (`@jgengine/core/runtime/simLoop`): a fixed `hz` accumulates real time and runs equal-dt steps behind a catch-up cap (`maxCatchUpSteps`, default 5) instead of spiralling; the default stays `"variable"` (one step per frame) so existing games are unchanged until they opt in. Under a fixed rate the shell renders entities at `ctx.sim.renderPose(id)` — the pose interpolated between the previous and current step (`@jgengine/core/runtime/poseInterpolation`), with teleports past `snapDistance` snapping — so a 20 Hz sim no longer stutters. `ctx.sim.tick()` counts steps and `InputFrame.tick` carries it over the wire; `ctx.sim.addStage({ phase, run })` inserts per-step work before movement, after movement, or after `onTick` (the hook a physics backend or netcode buffer registers through). System fixed-rate groups gain the same substep cap. For replay and rollback: `seededRng` streams expose `state()`/`restore()` (`rngStateOf`/`restoreRng` for any `ctx.rng`), `createSimSnapshotRegistry`/`createContextSimSnapshot` capture world, clock, loop, and rng cursor together, `createInputRecorder` logs frames by tick, and `HeadlessRunner` gains `snapshot()`/`restore()`/`tick()` — a test proves that replaying recorded input from a snapshot reproduces every entity pose.
+- **City and street races share one generator.** `extractCircuitRoute` lifts a sealed-off race lap from a city street network; city rules, editor baking, playground modes, and the shell renderer carry the same street dials through the resulting race surface and junction dressing.
+- **`ctx.particles` — the game-reachable particle seam.** Game logic queues one-shot bursts (`ctx.particles.burst(config, count)`) and keyed standing emitters (`attach`/`retune`/`detach`, with `follow` to track a scene entity) as plain serializable data (`@jgengine/core/vfx/particleDirector`); the shell auto-mounts a renderer that turns them into pooled GPU point clouds via the existing `createParticleSystem`/`ParticleField`, caps pool sizes by graphics quality (low 128 / medium 256 / high 512 per effect, degrading density instead of dropping effects), and reaps finished bursts. Dust, sparks, exhaust, and debris no longer require forking the shell; headless tests assert the requested effects straight off the director.
+- **`resolveSourceWalkerStep(source, cache, position, stepX, stepZ, options)`** (`@jgengine/core/movement/solidObstacles`) — `resolveWalkerStep` with no `GameContext`, for movement rules that live in a pure package with no React or three.js. `SolidObstacleSource`, `ObstacleReachCache`, `createObstacleReachCache`, `sourceObstacleReach`, `sourceObstaclesNear`, and `slideStep` are public alongside it instead of `@internal`, so a game no longer has to push the resolver up into its app layer and inject it back down. `resolveWalkerStep`'s doc now states that it already resolves X and Z separately, so a caller doing its own axis-split must hand it one axis per call.
+- **`tickRunCount(plan, id)`** (`@jgengine/core/time/serverTick`) — how many runs a plan owes a system, or 0 when it is not due.
+- **`grass()` exposes the clump/lighting knobs its shader already had.** `GrassEnvironmentConfig` gains optional `bladeBend`, `tuftRadius`, `colorVariation`, and `normalLift`, forwarded by the shell's environment renderer — a world descriptor can now author bushy wind-combed scrub instead of the fixed lawn-blade look; defaults unchanged.
+- **`TerrainDetailConfig.sweeps`** — the detail shader's two macro colour sweeps (sun-dried patches, cooler wet pockets) take per-world RGB multipliers instead of hardcoded meadow tints. The old green-leaning "lush pocket" default painted moss onto arid/ashen biomes; defaults are unchanged, so a desert world should set warm/neutral `sweeps` explicitly.
+- **`@jgengine/rapier`** — a Rapier-backed `PhysicsBackend` adapter with native capsules, shapecasts, rotation, CCD, joints, and collision queries.
+
+## 0.18.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.18.0`:** `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.15.0`; `@jgengine/github` is `0.5.0`.
+- **Register the presence reaper and redeploy your schema.** `jgPoses` gains `sessionId` / `kind` / `label` / `revokedAt` (all optional) and a `by_updated` index, and `createPresenceFunctions` now also returns `reapIdlePresence`. Re-export it (`export const { list, sync, leave, reapIdlePresence } = createPresenceFunctions(...)`) and add `crons.interval("jg presence reap", { seconds: 60 }, internal.presence.reapIdlePresence, {})`. Without it nothing deletes the row of a player who closed the tab — `list` filtered stale rows at read time but the table grew forever. `jgengineCronSpecs()` carries the new entry, and every spec now names the `module` (`"runtime"` / `"presence"`) it is exported from.
+- **`presence.sync` returns `{ pose, lastSeenAt, displaced }` instead of `null`,** and `presence.leave` marks the row revoked instead of deleting it (the reaper collects it once idle). A caller that ignored the return value is unaffected.
+
+### Changed
+
+- **`presence.sync` accepts a call with no `pose` at all,** which holds the stored position and moves only the liveness stamp. `createConvexPresenceSync` sends one itself when the pose gate has suppressed writes for 10s, so a standing player keeps their row alive without a pose write — and without the reaper collecting a live session.
+- **`PresencePoseRow` carries optional `sessionId` / `kind` / `label`,** so a nameplate reads off the presence row instead of joining against users per frame.
+
+### Added
+
+- **`createPresenceFunctions` gains the policy hooks the pose lane was missing** — `resolveSpawn(ctx, { serverId, userId, kind })` for where a session with no row starts (async and ctx-bearing, so a spawn can read the world, replacing a hardcoded origin), `poseRules` as a function of the actor `kind` so an agent need not obey a human's speed cap, `idleCutoffMs` / `maxReapPerRun` for the reaper, and optional `sessionId` on `sync` / `leave`: a second tab is a second row, syncing revokes the others, and the displaced session learns it on its next call through `displaced: true`.
+
+- **A command declares what it touches, so `runCommand` hydrates that and nothing else.** `CommandDef` gains an optional `scope(input, actorUserId)` returning `{ players?, chunkKeys? }`, evaluated before hydration; the registered `runCommand` mutation also accepts an explicit `scope` argument, which wins over the declared one. A game that never sets either keeps the whole-world default. `ServerLoopHooks.joinScope(userId, isNew)` does the same for `onNewPlayer`.
+- **`GameRuntime.commandScope` / `GameRuntime.joinScope`** expose those declarations to any host, alongside the pure helpers `resolveCommandScope` / `scopeWithActor` / `commandScopeEscape` (`@jgengine/core/runtime/commandRunner`).
+
 ### Fixed
 
+- **`runCommand` no longer reads the whole world on every command.** `LoadSnapshotScope` landed in 0.17 but only `helpers.loadSnapshot` accepted one, so the supported way to run a command — the registered `runCommand` mutation, a one-line delegation to `helpers.runCommand` — hydrated every member profile and every chunk however narrow the command was, and a game could only get bounded hydration by reimplementing the mutation. `runCommand`, `joinServer`, and `leaveServer` now hydrate a scope; a command whose `apply` dirties a player or chunk its scope never named is refused rather than persisted, since writing an unhydrated chunk overwrites the stored one with a blank. `flushSave` / `flushServerIfDue` / `tickActiveServers` / `flushDirtyServers` still hydrate everything, which is correct for what they write.
+
 ## 0.17.0
 
 ### Migrate
@@ -149,13 +272,18 @@ At publish, rename this heading to the new version and mirror the entries into
 - **`advanceStepCadence` (`@jgengine/core/audio/stepCadence`) — distance-driven footstep timing.** Pure state-in/state-out: feed it the ground distance a mover covered this frame and it reports how many steps landed and which foot led, so foley stays locked to distance instead of a wall-clock timer that desyncs the moment speed changes. Configurable stride, per-advance `strideScale` for crouch/sprint, and a shorter first step from rest so walking off is heard immediately.
 - **`resolveMusicState` (`@jgengine/core/audio/musicState`) — combat-reactive soundtrack selection.** The engine could already crossfade themes but nothing decided *when*, so every game re-handrolled the threshold and got a track that flapped as one enemy walked in and out of range. Give it a tier ladder (intensity → theme) and it resolves the theme to play: escalation is immediate, de-escalation waits for the tier's `holdMs` and needs intensity to fall a `release` margin below the tier it is leaving. Pure and serialisable.
 - **Synth voices take a `sustain` (`ToneVoice`/`NoiseVoice`).** Seconds held at full gain before the decay. Default 0 preserves every existing patch. Without it there was no way to author a *sustained* sound at all: every voice decayed to silence inside its duration, so a patch rendered once and looped as an ambient bed pulsed audibly once per loop. Set `sustain` to `duration` for a flat wind, rain, or machine-hum bed that loops seamlessly.
-
+- **A street race is a section of a city, sealed off.** `extractCircuitRoute(network, rules)` (`@jgengine/core/world/raceCircuit`) lifts a closed lap out of an existing street network — the same asphalt the open world already drives on — and seals every side street leaving it. Returns checkpoints ready for `raceTrack()`, start/finish, grid, corners, kerbs, and sectors. Circuit-mode networks take the same path (their loop edges are the cycle). The city volume kind gains a Race group (`race`, `raceLapLength`, `raceArterial`, …) that resolves a world-space `ResolvedRace` on `ResolvedCity.race`; `CityRenderer` draws the lap surface, kerbs, start/finish, grid, and barrier seals. Playground adds a Street race mode over the same shared slider set.
+- **Parked vehicles and junction signals on a city district.** `CityRules.parkedCars` / `signals` seed curb and pad fleets plus mast-arm signals (arterials) and sign posts (the rest); `ResolvedCity.vehicles` / `signals` hand them to `CityRenderer`.
 - **`ModelMaterialOverride.rim` — a fresnel rim light on any entity/object model.** `{ color, strength, power }` adds a bright edge where the surface turns away from the viewer, patched into the material's own shader so it shadows, fogs, and tonemaps with the body rather than floating in front of it. This is the standard fix for an actor that shares a value band with its ground: no albedo choice separates a body from terrain lit by the same key, but an edge does. Omit for no rim (default).
 
 ### Fixed
 
 - **Noise voices longer than the shared noise buffer no longer go silent partway through.** The 1-second buffer is sampled from a random offset, so any `NoiseVoice` whose duration exceeded the remainder ran off the end and finished in silence — invisible on short impact bursts, fatal for anything sustained. The source now wraps; the voice still ends on time.
 
+- **CityRenderer junctions use the welded carriageway-union seam end-to-end.** District roads go through `buildTrimmedIntersections` + `buildIntersectionMarkings` with the same compact opts as StreetGeometryPreview / playground (`curbReturnRadius: 2`, `apronMargin: 0.25`). Plaza hull aprons, fallback discs, and fat zebra ladders are gone; race resurfacing stops at junction mouths so welded patches stay visible.
+- **Denser urban fabric for metro/Manhattan districts.** Commercial class setbacks/spacing tighten toward a streetwall; slabs/towers pick L-plans and mid-block courts; dense blocks push footprints to the curb and paint courtyards as hard courts rather than lawn leftovers.
+- **City and track are one slider surface again.** `CityRules` and the editor `generate_streets` bake now forward every `StreetNetworkRules` dial (`elevation`, `maxGrade`, `compactness`, `sidewalkWidth`, `outline`, `residentialBranches`); `check-street-rule-parity` fails CI if either drifts. Playground no longer hides layout sliders when you switch modes — modes are presets over one shared set.
+- **City facades dissolve their window stripes before they alias into speckled static**, and ground floors now read as storefronts rather than repeating floor 30. Block interiors paint developed fabric instead of raw lawn, and crosswalks only land at real junctions.
 - **`terrain({ detail: { material: { tint } } })` separates a ground texture's grain from its hue.** A detail material's colour map used to replace the terrain's authored colour outright, so the biome palette, macro sweeps, and slope-rock blend under it were painted over and a whole region flattened to the texture's single hue — despite the API documenting that it "blends with, never replaces". `tint` defaults to 1 (the existing behaviour, so no shipped game changes); drop it toward 0 to keep the authored colour and take only the map's light and shade.
 - **`sky({ gradientExponent, cloudiness })` are now authorable — and `sky()` no longer silently drops them.** `gradientExponent` controls how fast the gradient reaches `zenithColor` off the horizon (default 0.65, unchanged): below 1 pulls the zenith hue down into the frame, which is what an eye-level camera in flat terrain actually needs — at the default the sky reads as one horizon-coloured wash however saturated the authored zenith is. `cloudiness` (default 0.35, unchanged) is the procedural cloud-band opacity.
 - **A model that throws while rendering is now reported instead of vanishing (#1588).** `ModelFallbackBoundary` swapped in its fallback (usually nothing) and stayed silent: `probes.fallbacks` stayed empty, no warning was logged, and an entity simply disappeared. It now reports a new `renderError` fallback cause on every failed render and warns once with the model url and the caught error.

package/dist/GamePlayerShell.js

@@ -6,6 +6,7 @@ import { deriveTouchScheme, withTouchCodes, DEFAULT_TOUCH_STYLE } from "@jgengin
 import { activeTouchControlsMode } from "@jgengine/core/input/touchControlsMode";
 import { normalizePointerToAxis } from "@jgengine/core/input/pointerAxis";
 import { createGameContext } from "@jgengine/core/runtime/gameContext";
+import { activeActionCodes } from "@jgengine/core/game/controlGate";
 import { useDisplayProfile } from "@jgengine/react/display";
 import { RotateDeviceScreen } from "@jgengine/react/rotateDevice";
 import { createSettingsStore } from "@jgengine/core/settings/settingsModel";
@@ -24,6 +25,7 @@ import { OrientationHint } from "./touch/OrientationHint.js";
 import { useTouchStyle, useTouchJoystickVariant, useGraphicsSettings } from "./settings/appliedSettings.js";
 import { logRuntimeError, } from "./diagnostics/RuntimeDiagnostics.js";
 import { EMPTY_RESERVED } from "./shellConstants.js";
+import { JoinGate } from "./JoinGate.js";
 import { useShellMultiplayerSync } from "./useShellMultiplayerSync.js";
 import { ShellHudPresentation } from "./ShellHudPresentation.js";
 import { Shell3dPresentation } from "./Shell3dPresentation.js";
@@ -88,8 +90,8 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
     const effectiveInput = useMemo(() => applyBindingOverrides(playable.game.input ?? {}, bindingOverrides), [playable, bindingOverrides]);
     const rebindAction = useCallback((action, code) => setBindingOverrides(saveBindingOverride(playable.game.name, action, [code])), [playable]);
     const resetActionBinding = useCallback((action) => setBindingOverrides(clearBindingOverride(playable.game.name, action)), [playable]);
-    const tracker = useMemo(() => createActionStateTracker(toActionStateBindingMap(withTouchCodes(effectiveInput))), [effectiveInput]);
-    const graphics = useGraphicsSettings(settingsStore, playable.shadows ?? true);
+    const tracker = useMemo(() => createActionStateTracker(toActionStateBindingMap(withTouchCodes(ctx === null ? effectiveInput : activeActionCodes(ctx, effectiveInput)))), [ctx, effectiveInput]);
+    const graphics = useGraphicsSettings(settingsStore, playable.shadows ?? true, playable.graphics);
     const trackPointerAxis = (event) => {
         const rect = wrapperRef.current?.getBoundingClientRect();
         if (rect === undefined)
@@ -193,13 +195,16 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
             setCtx(null);
         };
     }, [playable, userId]);
-    useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef, setRemotePlayers);
+    const authoritativeFrameRef = useRef(null);
+    const join = useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef, setRemotePlayers, authoritativeFrameRef);
     useEffect(() => {
         wrapperRef.current?.focus();
     }, [ctx]);
     useSyncExternalStore(ctx?.subscribe ?? (() => () => undefined), ctx?.version ?? (() => 0), ctx?.version ?? (() => 0));
     if (ctx === null)
         return _jsx("div", { className: "h-full w-full bg-neutral-950" });
+    if (join.status !== "joined")
+        return _jsx(JoinGate, { ...join });
     const cameraConfig = playable.camera?.followEntityId !== undefined
         ? playable.camera
         : { ...playable.camera, followEntityId: ctx.player.possession.active(userId) };
@@ -219,6 +224,7 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
         touchSink,
         touchJoystickVariant,
         analogRef,
+        inputBindings: effectiveInput,
         orientationGate,
         orientationGateEl,
         coarsePointer,
@@ -238,5 +244,5 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
                 return;
             posterSettledRef.current = true;
             setPosterFrozen(true);
-        } }));
+        }, authoritativeFrameRef: authoritativeFrameRef }));
 }

package/dist/JoinGate.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+/**
+ * Blocking join feedback; callers may supply their own copy and classes.
+ * @capability join-gate block gameplay until joined and show failures with retry
+ */
+export declare function JoinGate({ status, failureReason, retry, joiningLabel, failedLabel, retryLabel, className, children, renderJoining, renderFailure }: {
+    status: "joining" | "joined" | "failed";
+    failureReason?: string | null;
+    retry: () => void;
+    joiningLabel?: ReactNode;
+    failedLabel?: ReactNode;
+    retryLabel?: ReactNode;
+    className?: string;
+    children?: ReactNode;
+    renderJoining?: () => ReactNode;
+    renderFailure?: (reason: string | null, retry: () => void) => ReactNode;
+}): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;

package/dist/JoinGate.js

@@ -0,0 +1,14 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Blocking join feedback; callers may supply their own copy and classes.
+ * @capability join-gate block gameplay until joined and show failures with retry
+ */
+export function JoinGate({ status, failureReason, retry, joiningLabel = "Joining world…", failedLabel = "Unable to join", retryLabel = "Retry", className, children, renderJoining, renderFailure }) {
+    if (status === "joined")
+        return children;
+    if (status === "joining" && renderJoining)
+        return renderJoining();
+    if (status === "failed" && renderFailure)
+        return renderFailure(failureReason ?? null, retry);
+    return _jsxs("div", { className: className, "data-join-gate": status, style: { display: "grid", placeContent: "center", textAlign: "center", width: "100%", height: "100%", background: "var(--jg-surface, #171717)", color: "var(--jg-text, #fafafa)" }, children: [_jsx("p", { role: status === "failed" ? "alert" : "status", children: status === "failed" ? failedLabel : joiningLabel }), status === "failed" && _jsxs(_Fragment, { children: [_jsx("p", { children: failureReason }), _jsx("button", { type: "button", onClick: retry, children: retryLabel })] })] });
+}

package/dist/Shell3dPresentation.d.ts

@@ -3,16 +3,18 @@ import type { PointerAxisState } from "@jgengine/core/input/pointerAxis";
 import type { ActionStateTracker } from "@jgengine/core/input/actionBindings";
 import type { BindingOverrides } from "@jgengine/core/input/bindingOverrides";
 import type { TouchJoystickVariant, TouchScheme, TouchStyle } from "@jgengine/core/input/touchScheme";
+import type { GraphicsProfile } from "@jgengine/core/settings/graphicsProfile";
 import { type GraphicsQuality, type SettingsStore } from "@jgengine/core/settings/settingsModel";
 import type { PresencePoseRow } from "@jgengine/core/runtime/transport";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
 import type { AudioEngine } from "./audio/audioEngine.js";
 import type { ShellMultiplayer } from "./multiplayer.js";
 import type { PlayableGame } from "./registry.js";
+import type { AuthoritativeFrameHandler } from "./worldSync.js";
 import { type TouchCodeSink } from "./touch/TouchControlsOverlay.js";
 import type { RuntimeDiagnostic } from "./diagnostics/RuntimeDiagnostics.js";
 /** 3D play surface: canvas, world overlays, and shared chrome. @internal */
-export declare function Shell3dPresentation({ playable, ctx, multiplayer, tracker, pointerAxisRef, gateRef, wrapperRef, f2HeldRef, yawRef, pitchRef, primaryClickRef, cameraDraggingRef, serverIdRef, remotePlayers, touchScheme, touchSink, touchStyle, touchJoystickVariant, analogRef, orientationGate, orientationGateEl, coarsePointer, compact, graphics, settingsStore, bindingOverrides, rebindAction, resetActionBinding, diagnostics, devtoolsEnabled, devtoolsOpen, setDevtoolsOpen, reportRuntimeError, trackPointerAxis, deactivatePointerAxis, audioEngine, poster, posterFrozen, onPosterSettled, }: {
+export declare function Shell3dPresentation({ playable, ctx, multiplayer, tracker, pointerAxisRef, gateRef, wrapperRef, f2HeldRef, yawRef, pitchRef, primaryClickRef, cameraDraggingRef, serverIdRef, remotePlayers, touchScheme, touchSink, touchStyle, touchJoystickVariant, analogRef, inputBindings, orientationGate, orientationGateEl, coarsePointer, compact, graphics, settingsStore, bindingOverrides, rebindAction, resetActionBinding, diagnostics, devtoolsEnabled, devtoolsOpen, setDevtoolsOpen, reportRuntimeError, trackPointerAxis, deactivatePointerAxis, audioEngine, poster, posterFrozen, onPosterSettled, authoritativeFrameRef, }: {
     playable: PlayableGame;
     ctx: GameContext;
     multiplayer: ShellMultiplayer | null;
@@ -32,6 +34,7 @@ export declare function Shell3dPresentation({ playable, ctx, multiplayer, tracke
     touchStyle: TouchStyle;
     touchJoystickVariant: TouchJoystickVariant;
     analogRef: MutableRefObject<Readonly<Record<string, number>> | null>;
+    inputBindings: typeof playable.game.input;
     orientationGate: boolean;
     orientationGateEl: React.ReactNode;
     coarsePointer: boolean;
@@ -41,6 +44,7 @@ export declare function Shell3dPresentation({ playable, ctx, multiplayer, tracke
         dpr: number;
         uiScale: number;
         quality: GraphicsQuality;
+        profile: GraphicsProfile;
     };
     settingsStore: SettingsStore;
     bindingOverrides: BindingOverrides;
@@ -60,4 +64,7 @@ export declare function Shell3dPresentation({ playable, ctx, multiplayer, tracke
     poster: boolean;
     posterFrozen: boolean;
     onPosterSettled: () => void;
+    authoritativeFrameRef: {
+        current: AuthoritativeFrameHandler | null;
+    };
 }): import("react").JSX.Element;

package/dist/Shell3dPresentation.js

@@ -1,10 +1,12 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Canvas } from "@react-three/fiber";
 import { useMemo, useRef, useState, } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
 import { contextVerbInput, } from "@jgengine/core/interaction/contextMenu";
 import { createSelectionSet, isMarquee, screenRect, selectWithinRect, } from "@jgengine/core/scene/selection";
 import { DEFAULT_PICKUP_RADIUS } from "@jgengine/core/game/worldItem";
 import { CAMERA_FRUSTUM_DEFAULTS } from "@jgengine/core/game/playableGame";
+import { pixelPerfectFrustum, snapPixelPerfectPosition } from "@jgengine/core/game/pixelPerfect";
 import { BUILT_IN_SETTING_CATEGORIES, } from "@jgengine/core/settings/settingsModel";
 import { playControlsActive } from "@jgengine/core/game/controlGate";
 import { sky as resolveSkyDescriptor } from "@jgengine/core/world/features";
@@ -38,14 +40,36 @@ import { AudioSettingsBridge } from "./settings/appliedSettings.js";
 import { ConfiguredLighting, BackdropFog } from "./render/SceneLighting.js";
 import { WorldView, RemotePlayers } from "./world/WorldScene.js";
 import { FrameDriver } from "./drivers/FrameDriver.js";
+import { GamepadSource } from "./input/gamepadSource.js";
 import { createShellKeyHandlers, ShellDebugOverlays, ShellGameUiChrome } from "./ShellChrome.js";
 import { CombatPresentation } from "./CombatPresentation.js";
+import { WorldParticles } from "./world/WorldParticles.js";
+import { detectKtx2Support } from "./render/modelLoad.js";
 import { resolvePresentationEffects, resolveWorldOverlayBars, } from "./presentationResolve.js";
 const PRIMARY_CLICK_MOVE_THRESHOLD_PX = 6;
 const DEFAULT_BACKGROUND_COLOR = "#14161b";
+function PixelPerfectCamera({ pixelsPerUnit, integerScale }) {
+    const camera = useThree((state) => state.camera);
+    const size = useThree((state) => state.size);
+    useFrame(() => {
+        if (camera.isOrthographicCamera !== true)
+            return;
+        const frustum = pixelPerfectFrustum(size, pixelsPerUnit, integerScale === true);
+        camera.left = frustum.left;
+        camera.right = frustum.right;
+        camera.top = frustum.top;
+        camera.bottom = frustum.bottom;
+        camera.zoom = 1;
+        const snapped = snapPixelPerfectPosition(camera.position, pixelsPerUnit);
+        camera.position.set(snapped.x, snapped.y, snapped.z);
+        camera.updateProjectionMatrix();
+    }, 1);
+    return null;
+}
 /** 3D play surface: canvas, world overlays, and shared chrome. @internal */
-export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, pointerAxisRef, gateRef, wrapperRef, f2HeldRef, yawRef, pitchRef, primaryClickRef, cameraDraggingRef, serverIdRef, remotePlayers, touchScheme, touchSink, touchStyle, touchJoystickVariant, analogRef, orientationGate, orientationGateEl, coarsePointer, compact, graphics, settingsStore, bindingOverrides, rebindAction, resetActionBinding, diagnostics, devtoolsEnabled, devtoolsOpen, setDevtoolsOpen, reportRuntimeError, trackPointerAxis, deactivatePointerAxis, audioEngine, poster, posterFrozen, onPosterSettled, }) {
+export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, pointerAxisRef, gateRef, wrapperRef, f2HeldRef, yawRef, pitchRef, primaryClickRef, cameraDraggingRef, serverIdRef, remotePlayers, touchScheme, touchSink, touchStyle, touchJoystickVariant, analogRef, inputBindings, orientationGate, orientationGateEl, coarsePointer, compact, graphics, settingsStore, bindingOverrides, rebindAction, resetActionBinding, diagnostics, devtoolsEnabled, devtoolsOpen, setDevtoolsOpen, reportRuntimeError, trackPointerAxis, deactivatePointerAxis, audioEngine, poster, posterFrozen, onPosterSettled, authoritativeFrameRef, }) {
     const GameUI = playable.GameUI;
+    const ktx2SupportDetected = useRef(false);
     const WorldOverlay = playable.WorldOverlay;
     const pointerService = useMemo(() => createPointerService(), []);
     const selection = useMemo(() => createSelectionSet(), [playable]);
@@ -67,7 +91,7 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
     const worldSky = resolveWorldSky(playable.game.world);
     const world = playable.game.world;
     const biomeBands = world?.kind === "environment" ? world.terrain?.biomeBands : undefined;
-    const AutoEnvironment = playable.environment ??
+    const AutoEnvironment = (typeof playable.environment === "function" ? playable.environment : undefined) ??
         (world?.kind === "environment"
             ? () => _jsx(EnvironmentScene, { feature: world })
             : world?.kind === "place"
@@ -279,7 +303,12 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
                             else if (event.deltaY > 0 && ctx.game.commands.has("ui.hotbarScrollPrev")) {
                                 ctx.game.commands.run("ui.hotbarScrollPrev", {});
                             }
-                        }, children: _jsxs(GameViewportProvider, { platforms: playable.platforms, children: [_jsxs(Canvas, { frameloop: poster && posterFrozen ? "demand" : "always", orthographic: orthographic, camera: orthographic
+                        }, children: _jsxs(GameViewportProvider, { platforms: playable.platforms, children: [_jsxs(Canvas, { onCreated: ({ gl }) => {
+                                        if (ktx2SupportDetected.current)
+                                            return;
+                                        ktx2SupportDetected.current = true;
+                                        detectKtx2Support(gl);
+                                    }, frameloop: poster && posterFrozen ? "demand" : "always", orthographic: orthographic, camera: orthographic
                                         ? {
                                             zoom: playable.camera?.frustum?.zoom ?? CAMERA_FRUSTUM_DEFAULTS.zoom,
                                             near: playable.camera?.frustum?.near ?? CAMERA_FRUSTUM_DEFAULTS.near,
@@ -289,9 +318,9 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
                                             fov: playable.camera?.frustum?.fov ?? CAMERA_FRUSTUM_DEFAULTS.fov,
                                             near: playable.camera?.frustum?.near ?? CAMERA_FRUSTUM_DEFAULTS.near,
                                             far: playable.camera?.frustum?.far ?? CAMERA_FRUSTUM_DEFAULTS.far,
-                                        }, shadows: graphics.shadows, dpr: [Math.min(1, graphics.dpr), graphics.dpr], gl: { preserveDrawingBuffer: true }, style: { touchAction: "none" }, children: [backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? (_jsx(EnvironmentLighting, { skyColor: lighting?.hemisphere?.skyColor ?? "#87b5e0", groundColor: lighting?.hemisphere?.groundColor ?? "#3d4a38", sunDirection: lighting?.directional?.[0]?.position, sunColor: lighting?.directional?.[0]?.color ?? "#fff2d6" })) : null, lighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: lighting })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 })] })) : null, effectiveSky !== undefined ? (effectiveSky.timeOfDay ? (_jsx(TimeOfDayDaylight, { sky: effectiveSky, clock: ctx.time, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) })) : (_jsx(SkyDaylight, { sky: effectiveSky, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) }))) : null, _jsx(BackdropFog, { fog: backdrop?.fog }), _jsxs(GameProvider, { context: ctx, children: [_jsx(CullingProvider, { config: playable.visibility, children: _jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, objectStyles: playable.objectStyles, environment: AutoEnvironment, assets: playable.game.assets, renderEntity: playable.renderEntity, renderObject: playable.renderObject, selectedIds: selectedIds, hideLocalActor: firstPerson }) }), WorldOverlay !== undefined ? (_jsx("group", { userData: CAMERA_TRANSPARENT_USERDATA, children: _jsx(WorldOverlay, { ctx: ctx }) })) : null, bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxDistance === undefined ? {} : { maxDistance: bars.maxDistance }), ...(bars.occlude === undefined ? {} : { occlude: bars.occlude }) })) : null, nameplates !== null ? (_jsx(WorldNameplates, { statId: nameplates.statId, roles: nameplates.roles, resolveRole: resolveEntityRole, ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }), ...(nameplates.showHealth === undefined ? {} : { showHealth: nameplates.showHealth }) })) : null, _jsx(WorldItems, { config: playable.worldItem }), _jsx(CombatPresentation, { effects: effects }), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(AudioListener, { engine: audioEngine }), _jsx(EntityAudioEmitters, { engine: audioEngine, entitySounds: playable.entitySounds }), _jsx(ObjectAudioEmitters, { engine: audioEngine, objectSounds: playable.objectSounds }), _jsx(GameCameraRig, { yawRef: yawRef, pitchRef: pitchRef, config: cameraConfig, viewmodel: playable.viewmodel, pointerControls: pointerUsesLeft, panKeysEnabled: rtsPanKeysEnabled, director: ctx.camera, onDragChange: (dragging) => {
+                                        }, shadows: graphics.shadows, dpr: [Math.min(1, graphics.dpr), graphics.dpr], gl: { preserveDrawingBuffer: true }, style: { touchAction: "none" }, children: [orthographic && playable.camera?.pixelPerfect !== undefined ? (_jsx(PixelPerfectCamera, { ...playable.camera.pixelPerfect })) : null, backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? (_jsx(EnvironmentLighting, { source: playable.environmentSource, skyColor: lighting?.hemisphere?.skyColor ?? "#87b5e0", groundColor: lighting?.hemisphere?.groundColor ?? "#3d4a38", sunDirection: lighting?.directional?.[0]?.position, sunColor: lighting?.directional?.[0]?.color ?? "#fff2d6" })) : null, lighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: lighting, profile: graphics.profile })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 })] })) : null, effectiveSky !== undefined ? (effectiveSky.timeOfDay ? (_jsx(TimeOfDayDaylight, { sky: effectiveSky, clock: ctx.time, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) })) : (_jsx(SkyDaylight, { sky: effectiveSky, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) }))) : null, _jsx(BackdropFog, { fog: backdrop?.fog }), _jsxs(GameProvider, { context: ctx, children: [_jsx(CullingProvider, { config: playable.visibility, drawDistance: graphics.profile.drawDistance, children: _jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, objectStyles: playable.objectStyles, environment: AutoEnvironment, assets: playable.game.assets, renderEntity: playable.renderEntity, renderObject: playable.renderObject, selectedIds: selectedIds, hideLocalActor: firstPerson }) }), WorldOverlay !== undefined ? (_jsx("group", { userData: CAMERA_TRANSPARENT_USERDATA, children: _jsx(WorldOverlay, { ctx: ctx }) })) : null, bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxDistance === undefined ? {} : { maxDistance: bars.maxDistance }), ...(bars.occlude === undefined ? {} : { occlude: bars.occlude }) })) : null, nameplates !== null ? (_jsx(WorldNameplates, { statId: nameplates.statId, roles: nameplates.roles, resolveRole: resolveEntityRole, ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }), ...(nameplates.showHealth === undefined ? {} : { showHealth: nameplates.showHealth }) })) : null, _jsx(WorldItems, { config: playable.worldItem }), _jsx(WorldParticles, { quality: graphics.quality, particleCap: graphics.profile.particleCap }), _jsx(CombatPresentation, { effects: effects }), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(AudioListener, { engine: audioEngine }), _jsx(EntityAudioEmitters, { engine: audioEngine, entitySounds: playable.entitySounds }), _jsx(ObjectAudioEmitters, { engine: audioEngine, objectSounds: playable.objectSounds }), _jsx(GameCameraRig, { yawRef: yawRef, pitchRef: pitchRef, config: cameraConfig, viewmodel: playable.viewmodel, pointerControls: pointerUsesLeft, panKeysEnabled: rtsPanKeysEnabled, director: ctx.camera, onDragChange: (dragging) => {
                                                         cameraDraggingRef.current = dragging;
-                                                    } }), _jsx(PointerProbe, { service: pointerService })] }), _jsx(RemotePlayers, { rows: remotePlayers }), _jsx(FrameDriver, { ctx: ctx, playable: playable, tracker: tracker, yawRef: yawRef, pitchRef: pitchRef, primaryClickRef: primaryClickRef, pointerAxisRef: pointerAxisRef, analogRef: analogRef, gateRef: gateRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef, pointerService: pointerService, pointerAim: pointer?.aim === true, pingCommand: pointer?.pingCommand, poster: poster, onPosterSettled: onPosterSettled }), _jsx(DevtoolsRendererProbe, {}), resolvedLook.postProcessing !== undefined && resolvedLook.postProcessing.enabled !== false ? (_jsx(PostProcessing, { config: resolvedLook.postProcessing, quality: graphics.quality })) : null] }), !poster &&
+                                                    } }), _jsx(PointerProbe, { service: pointerService })] }), _jsx(RemotePlayers, { rows: remotePlayers }), _jsx(FrameDriver, { ctx: ctx, playable: playable, tracker: tracker, yawRef: yawRef, pitchRef: pitchRef, primaryClickRef: primaryClickRef, pointerAxisRef: pointerAxisRef, analogRef: analogRef, gateRef: gateRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef, pointerService: pointerService, pointerAim: pointer?.aim === true, pingCommand: pointer?.pingCommand, poster: poster, onPosterSettled: onPosterSettled, authoritativeFrameRef: authoritativeFrameRef }), _jsx(GamepadSource, { tracker: tracker, bindings: inputBindings ?? {}, analogRef: analogRef, input: ctx.input }), _jsx(DevtoolsRendererProbe, {}), resolvedLook.postProcessing !== undefined && resolvedLook.postProcessing.enabled !== false ? (_jsx(PostProcessing, { config: resolvedLook.postProcessing, quality: graphics.quality, stages: graphics.profile.postStages })) : null] }), !poster &&
                                     !orientationGate &&
                                     coarsePointer &&
                                     controlsActive &&

package/dist/ShellChrome.d.ts

@@ -26,10 +26,12 @@ export declare function ShellDebugOverlays({ ctx, playable, multiplayer, diagnos
 export type ShellKeyHandlers = {
     onKeyDown: (event: {
         code: string;
+        target?: EventTarget | null;
         preventDefault: () => void;
     }) => void;
     onKeyUp: (event: {
         code: string;
+        target?: EventTarget | null;
     }) => void;
     onBlur: () => void;
 };

package/dist/ShellChrome.js

@@ -16,6 +16,12 @@ export function ShellDebugOverlays({ ctx, playable, multiplayer, diagnostics, de
 export function createShellKeyHandlers({ f2HeldRef, tracker, devtoolsEnabled, setDevtoolsOpen, controlsActive, exitPointerLockOnDevtools = false, }) {
     return {
         onKeyDown: (event) => {
+            const target = event.target;
+            if (target?.closest?.("input, textarea, select, [contenteditable]:not([contenteditable=false])")) {
+                f2HeldRef.current = false;
+                tracker.reset();
+                return;
+            }
             if (event.code === "F2") {
                 event.preventDefault();
                 f2HeldRef.current = true;

package/dist/TerritoryOverlay.d.ts

@@ -0,0 +1,21 @@
+import type { CSSProperties, ReactNode } from "react";
+/** A placement footprint cell and its authoritative preview status. */
+export type TerritoryPreviewCell = {
+    key: string;
+    x: number;
+    z: number;
+    status: "owned" | "claimable" | "blocked";
+};
+/**
+ * Placement footprint feedback with inline claim cost and affordability.
+ * @capability territory-overlay show footprint ownership, claim cost, and affordability
+ */
+export declare function TerritoryOverlay({ cells, cost, affordable, formatCost, renderCell, className, style }: {
+    cells: readonly TerritoryPreviewCell[];
+    cost: number;
+    affordable: boolean;
+    formatCost?: (cost: number) => ReactNode;
+    renderCell?: (cell: TerritoryPreviewCell) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;

package/dist/TerritoryOverlay.js

@@ -0,0 +1,9 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Placement footprint feedback with inline claim cost and affordability.
+ * @capability territory-overlay show footprint ownership, claim cost, and affordability
+ */
+export function TerritoryOverlay({ cells, cost, affordable, formatCost = String, renderCell, className, style }) {
+    const blocked = cells.some((cell) => cell.status === "blocked");
+    return _jsxs("div", { className: className, style: { pointerEvents: "none", ...style }, "data-territory-overlay": true, children: [_jsx("div", { style: { display: "flex", gap: 3 }, children: cells.map((cell) => _jsx("span", { "data-territory-cell": cell.status, title: `${cell.x}, ${cell.z}: ${cell.status}`, children: renderCell ? renderCell(cell) : _jsx("span", { "aria-label": cell.status, style: { display: "inline-block", width: 8, height: 8, borderRadius: 2, background: cell.status === "owned" ? "var(--jg-accent, #5fc2a8)" : cell.status === "claimable" ? "#d6a548" : "#d96969" } }) }, cell.key)) }), _jsx("output", { "aria-live": "polite", "data-affordable": affordable, "data-blocked": blocked, children: blocked ? "Land unavailable" : _jsxs(_Fragment, { children: ["Land: ", formatCost(cost), affordable ? "" : " — Insufficient funds"] }) })] });
+}

package/dist/audio/AudioComponents.js

@@ -1,10 +1,17 @@
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
+import { Quaternion, Vector3 } from "three";
 import { useGameContext } from "@jgengine/react/provider";
 export function AudioListener({ engine }) {
     const camera = useThree((state) => state.camera);
     useFrame(() => {
-        engine.setListenerPose({ x: camera.position.x, y: camera.position.y, z: camera.position.z });
+        const direction = camera.getWorldDirection(new Vector3());
+        const up = camera.up.clone().applyQuaternion(camera.getWorldQuaternion(new Quaternion()));
+        engine.setListenerPose({
+            position: { x: camera.position.x, y: camera.position.y, z: camera.position.z },
+            forward: { x: direction.x, y: direction.y, z: direction.z },
+            up: { x: up.x, y: up.y, z: up.z },
+        });
     });
     return null;
 }

package/dist/audio/audioEngine.d.ts

@@ -6,6 +6,12 @@ export interface Vec3 {
     y: number;
     z: number;
 }
+/** Position and orientation for a spatial-audio listener. */
+export interface ListenerPose {
+    position: Vec3;
+    forward: Vec3;
+    up: Vec3;
+}
 export interface AudioSceneConfig {
     sounds?: Record<string, SoundDef>;
     buses?: Record<string, AudioBusDef>;
@@ -23,7 +29,7 @@ export interface AudioEmitterHandle {
     stop(): void;
 }
 export interface AudioEngine {
-    setListenerPose(position: Vec3): void;
+    setListenerPose(pose: ListenerPose | Vec3): void;
     playOneShot(soundId: string, position?: Vec3): void;
     playLoop(soundId: string, position?: Vec3): AudioEmitterHandle | null;
     /** Crossfade the procedural soundtrack to `themeId` (null fades out). No-op when no `music` catalog is configured. */