@jgengine/shell 0.18.0 → 0.19.0

package/dist/camera/rigMath.d.ts

@@ -136,6 +136,23 @@ export interface ResolvedChase {
     velocityYawResponse: number;
     /** Exponential smoothing rate the anchor yaw follows the body's facing with (#1370). `Infinity` restores the legacy rigid follow. */
     yawResponse: number;
+    fovBase: number;
+    fovMax: number;
+    fovSpeedForMax: number;
+    /** Exponential FOV smoothing rate; `Infinity` applies the curve unsmoothed. */
+    fovResponse: number;
+    distanceExtra: number;
+    distanceSpeedForMax: number;
+    /** Fraction of body pitch the boom follows; 0 keeps a level boom. */
+    pitchBlend: number;
+    pitchMax: number;
+    pitchResponse: number;
+    fovKickDecay: number;
+    fovKickMax: number;
+    lookBackAction: string | null;
+    collision: boolean;
+    collisionRadius: number;
+    collisionMinDistance: number;
 }
 /** @internal */
 export declare function resolveChase(config: ChaseCameraConfig | undefined): ResolvedChase;
@@ -143,6 +160,10 @@ export declare function resolveChase(config: ChaseCameraConfig | undefined): Res
  * @internal
  */
 export declare function leadFollowPoint(follow: Vec3, previous: Vec3, dt: number, resolved: ResolvedChase): Vec3;
+/** Velocity-lead the follow point along a known planar velocity, clamped to `leadMax`.
+ * @internal
+ */
+export declare function leadFromVelocity(follow: Vec3, velocity: Vec3, resolved: ResolvedChase): Vec3;
 /** One smoothing step of the chase rig's turn-bank roll (#286.10): roll opposes yaw rate, clamped and exponentially damped.
  * @internal
  */
@@ -159,14 +180,71 @@ export declare function resolveObserver(config: ObserverCameraConfig | undefined
  * @internal
  */
 export declare function observerPose(subject: Vec3, angle: number, resolved: ResolvedObserver, fov: number): CameraPose;
-/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing).
+/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing). `pitch` (nose-up positive) tilts the boom around the vehicle's right axis.
+ * @internal
+ */
+export declare function chaseDesiredPosition(follow: Vec3, yaw: number, resolved: ResolvedChase, pitch?: number, distance?: number): Vec3;
+/** Camera offset from the follow point for a boom `distance` back and `height` up, tilted by `pitch` (nose-up positive).
+ * @internal
+ */
+export declare function chaseBoomOffset(yaw: number, pitch: number, distance: number, height: number): Vec3;
+/** Look point ahead of / above a chased vehicle, tilted by `pitch` like the boom.
  * @internal
  */
-export declare function chaseDesiredPosition(follow: Vec3, yaw: number, resolved: ResolvedChase): Vec3;
-/** Look point ahead of / above a chased vehicle.
+export declare function chaseLookAt(follow: Vec3, yaw: number, resolved: ResolvedChase, pitch?: number): Vec3;
+/** Mutable per-rig chase state; {@link stepChase} advances it in place. */
+export interface ChaseRigState {
+    /** Smoothed camera offset from the led follow point; springing the offset, not the world position, keeps the boom length at any constant speed. */
+    offset: Vec3 | null;
+    anchorYaw: number | null;
+    lastYaw: number | null;
+    lastFollow: Vec3 | null;
+    roll: number;
+    pitch: number;
+    fov: number | null;
+    kick: number;
+    lookingBack: boolean;
+}
+/** @internal */
+export declare function createChaseRigState(): ChaseRigState;
+/** What the chase rig reads from its target each frame. */
+export interface ChaseSample {
+    follow: Vec3;
+    /** Body heading (radians). */
+    yaw: number;
+    /** Body `rotationX` (three.js convention: positive = nose down). */
+    bodyPitch: number;
+    /** Sim velocity when the entity publishes one; `null` falls back to the frame-to-frame position delta. */
+    velocity: Vec3 | null;
+    lookBack: boolean;
+    /** FOV impulse (degrees) queued since the last frame. */
+    fovKick: number;
+}
+/** One frame of chase output from {@link stepChase}. */
+export interface ChaseStepResult {
+    pose: CameraPose;
+    /** Camera roll to apply after the pose, radians. */
+    roll: number;
+    /** Forward chase yaw to report to the shell; unaffected by look-back. */
+    anchorYaw: number;
+    /** Planar speed used for FOV, distance and shake. */
+    speed: number;
+}
+/** Pulls a desired camera position in toward `pivot` when something blocks the boom. */
+export type ChaseBoomClamp = (pivot: Vec3, desired: Vec3) => Vec3;
+/**
+ * One frame of the chase rig: speed from sim velocity, smoothed FOV plus decaying kicks, drift-lag
+ * anchor yaw, pitch follow, distance by speed, look-back, and a boom spring that eases the offset
+ * from the target rather than its world position, so the camera holds its distance at speed.
+ * @internal
+ */
+export declare function stepChase(state: ChaseRigState, sample: ChaseSample, resolved: ResolvedChase, dt: number, clampBoom?: ChaseBoomClamp): ChaseStepResult;
+/**
+ * Where a blocked boom should put the camera: `hitDistance` along the pivot→desired ray, less
+ * `radius`, but never nearer the pivot than `minDistance`. `null` hit returns `desired` unchanged.
  * @internal
  */
-export declare function chaseLookAt(follow: Vec3, yaw: number, resolved: ResolvedChase): Vec3;
+export declare function clampBoomToHit(pivot: Vec3, desired: Vec3, hitDistance: number | null, radius: number, minDistance: number): Vec3;
 /**
  * Drift-lag (#1051): the yaw the chase anchor should aim before temporal
  * smoothing. When the target slides, its planar `velocity` diverges from its

package/dist/camera/rigMath.js

@@ -253,6 +253,9 @@ export function lockOnPose(player, target, config, fov) {
 const DEFAULT_CHASE_YAW_RESPONSE = 5;
 /** @internal */
 export function resolveChase(config) {
+    const fovSpeedForMax = config?.fov?.speedForMax ?? 24;
+    const collision = config?.collision ?? true;
+    const collisionBlock = typeof collision === "object" ? collision : undefined;
     return {
         distance: config?.distance ?? 6,
         height: config?.height ?? 2.6,
@@ -268,16 +271,39 @@ export function resolveChase(config) {
         velocityYawMinSpeed: config?.velocityYaw?.minSpeed ?? 4,
         velocityYawResponse: config?.velocityYaw?.response ?? 6,
         yawResponse: config?.yawResponse ?? DEFAULT_CHASE_YAW_RESPONSE,
+        fovBase: config?.fov?.base ?? 55,
+        fovMax: config?.fov?.max ?? 78,
+        fovSpeedForMax,
+        fovResponse: config?.fov?.response ?? 6,
+        distanceExtra: config?.distanceBySpeed?.extra ?? 0,
+        distanceSpeedForMax: config?.distanceBySpeed?.speedForMax ?? fovSpeedForMax,
+        pitchBlend: config?.pitchFollow === undefined ? 0 : config.pitchFollow.blend ?? 1,
+        pitchMax: config?.pitchFollow?.max ?? 0.6,
+        pitchResponse: config?.pitchFollow?.response ?? 5,
+        fovKickDecay: config?.fovKick?.decay ?? 7,
+        fovKickMax: config?.fovKick?.max ?? 20,
+        lookBackAction: config?.lookBackAction ?? null,
+        collision: collision !== false,
+        collisionRadius: collisionBlock?.radius ?? 0.3,
+        collisionMinDistance: collisionBlock?.minDistance ?? 0.8,
     };
 }
 /** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`.
  * @internal
  */
 export function leadFollowPoint(follow, previous, dt, resolved) {
-    if (resolved.leadTime <= 0 || dt <= 0)
+    if (dt <= 0)
         return follow;
-    let leadX = ((follow.x - previous.x) / dt) * resolved.leadTime;
-    let leadZ = ((follow.z - previous.z) / dt) * resolved.leadTime;
+    return leadFromVelocity(follow, { x: (follow.x - previous.x) / dt, y: 0, z: (follow.z - previous.z) / dt }, resolved);
+}
+/** Velocity-lead the follow point along a known planar velocity, clamped to `leadMax`.
+ * @internal
+ */
+export function leadFromVelocity(follow, velocity, resolved) {
+    if (resolved.leadTime <= 0)
+        return follow;
+    let leadX = velocity.x * resolved.leadTime;
+    let leadZ = velocity.z * resolved.leadTime;
     const magnitude = Math.hypot(leadX, leadZ);
     if (magnitude > resolved.leadMax) {
         leadX *= resolved.leadMax / magnitude;
@@ -327,28 +353,120 @@ export function observerPose(subject, angle, resolved, fov) {
         fov,
     };
 }
-/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing).
+/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing). `pitch` (nose-up positive) tilts the boom around the vehicle's right axis.
  * @internal
  */
-export function chaseDesiredPosition(follow, yaw, resolved) {
-    const back = forwardVector(yaw);
+export function chaseDesiredPosition(follow, yaw, resolved, pitch = 0, distance = resolved.distance) {
+    const offset = chaseBoomOffset(yaw, pitch, distance, resolved.height);
+    return { x: follow.x + offset.x, y: follow.y + offset.y, z: follow.z + offset.z };
+}
+/** Camera offset from the follow point for a boom `distance` back and `height` up, tilted by `pitch` (nose-up positive).
+ * @internal
+ */
+export function chaseBoomOffset(yaw, pitch, distance, height) {
+    const forward = forwardVector(yaw);
+    const cos = Math.cos(pitch);
+    const sin = Math.sin(pitch);
+    const along = -distance * cos - height * sin;
+    return { x: forward.x * along, y: -distance * sin + height * cos, z: forward.z * along };
+}
+/** Look point ahead of / above a chased vehicle, tilted by `pitch` like the boom.
+ * @internal
+ */
+export function chaseLookAt(follow, yaw, resolved, pitch = 0) {
+    const forward = forwardVector(yaw);
+    const cos = Math.cos(pitch);
+    const sin = Math.sin(pitch);
+    const along = 2 * cos - resolved.lookHeight * sin;
     return {
-        x: follow.x - back.x * resolved.distance,
-        y: follow.y + resolved.height,
-        z: follow.z - back.z * resolved.distance,
+        x: follow.x + forward.x * along,
+        y: follow.y + 2 * sin + resolved.lookHeight * cos,
+        z: follow.z + forward.z * along,
     };
 }
-/** Look point ahead of / above a chased vehicle.
+/** @internal */
+export function createChaseRigState() {
+    return { offset: null, anchorYaw: null, lastYaw: null, lastFollow: null, roll: 0, pitch: 0, fov: null, kick: 0, lookingBack: false };
+}
+/**
+ * One frame of the chase rig: speed from sim velocity, smoothed FOV plus decaying kicks, drift-lag
+ * anchor yaw, pitch follow, distance by speed, look-back, and a boom spring that eases the offset
+ * from the target rather than its world position, so the camera holds its distance at speed.
  * @internal
  */
-export function chaseLookAt(follow, yaw, resolved) {
-    const forward = forwardVector(yaw);
+export function stepChase(state, sample, resolved, dt, clampBoom) {
+    const { follow, yaw } = sample;
+    const last = state.lastFollow ?? follow;
+    const velocity = sample.velocity ?? (dt > 0 ? { x: (follow.x - last.x) / dt, y: 0, z: (follow.z - last.z) / dt } : { x: 0, y: 0, z: 0 });
+    state.lastFollow = follow;
+    const speed = Math.hypot(velocity.x, velocity.z);
+    const lastYaw = state.lastYaw ?? yaw;
+    state.lastYaw = yaw;
+    state.roll = bankRollStep(state.roll, yaw, lastYaw, dt, resolved);
+    const targetFov = speedToFov(speed, { base: resolved.fovBase, max: resolved.fovMax, speedForMax: resolved.fovSpeedForMax });
+    state.fov =
+        state.fov === null || !Number.isFinite(resolved.fovResponse)
+            ? targetFov
+            : state.fov + (targetFov - state.fov) * smoothBlend(dt, resolved.fovResponse);
+    state.kick = clamp(state.kick * Math.exp(-resolved.fovKickDecay * dt) + sample.fovKick, -resolved.fovKickMax, resolved.fovKickMax);
+    let targetYaw = yaw;
+    let response = resolved.yawResponse;
+    if (resolved.velocityYawBlend > 0) {
+        targetYaw = velocityYawTarget(yaw, velocity, resolved);
+        response = resolved.velocityYawResponse;
+    }
+    const anchorYaw = Number.isFinite(response)
+        ? smoothYaw(state.anchorYaw ?? targetYaw, targetYaw, response, dt)
+        : targetYaw;
+    state.anchorYaw = anchorYaw;
+    const pitchTarget = clamp(-sample.bodyPitch * resolved.pitchBlend, -resolved.pitchMax, resolved.pitchMax);
+    state.pitch =
+        resolved.pitchBlend <= 0 ? 0 : state.pitch + (pitchTarget - state.pitch) * smoothBlend(dt, resolved.pitchResponse);
+    const snap = state.offset === null || sample.lookBack !== state.lookingBack;
+    state.lookingBack = sample.lookBack;
+    const boomYaw = sample.lookBack ? anchorYaw + Math.PI : anchorYaw;
+    const boomPitch = sample.lookBack ? -state.pitch : state.pitch;
+    const extra = resolved.distanceSpeedForMax > 0 ? resolved.distanceExtra * clamp(speed / resolved.distanceSpeedForMax, 0, 1) : 0;
+    const led = sample.lookBack ? follow : leadFromVelocity(follow, velocity, resolved);
+    const desiredOffset = chaseBoomOffset(boomYaw, boomPitch, resolved.distance + extra, resolved.height);
+    let offset = snap || state.offset === null ? desiredOffset : springArmStep(state.offset, desiredOffset, resolved.springDamping, dt);
+    if (clampBoom !== undefined) {
+        const up = chaseLookAt(led, boomYaw, resolved, boomPitch);
+        const pivot = { x: led.x, y: up.y, z: led.z };
+        const wanted = { x: led.x + offset.x, y: led.y + offset.y, z: led.z + offset.z };
+        const allowed = clampBoom(pivot, wanted);
+        offset = { x: allowed.x - led.x, y: allowed.y - led.y, z: allowed.z - led.z };
+    }
+    state.offset = offset;
     return {
-        x: follow.x + forward.x * 2,
-        y: follow.y + resolved.lookHeight,
-        z: follow.z + forward.z * 2,
+        pose: {
+            position: { x: led.x + offset.x, y: led.y + offset.y, z: led.z + offset.z },
+            lookAt: chaseLookAt(led, boomYaw, resolved, boomPitch),
+            fov: state.fov + state.kick,
+        },
+        roll: sample.lookBack ? -state.roll : state.roll,
+        anchorYaw,
+        speed,
     };
 }
+/**
+ * Where a blocked boom should put the camera: `hitDistance` along the pivot→desired ray, less
+ * `radius`, but never nearer the pivot than `minDistance`. `null` hit returns `desired` unchanged.
+ * @internal
+ */
+export function clampBoomToHit(pivot, desired, hitDistance, radius, minDistance) {
+    if (hitDistance === null)
+        return desired;
+    const dx = desired.x - pivot.x;
+    const dy = desired.y - pivot.y;
+    const dz = desired.z - pivot.z;
+    const length = Math.hypot(dx, dy, dz);
+    if (length <= 1e-6)
+        return desired;
+    const allowed = clamp(hitDistance - radius, Math.min(minDistance, length), length);
+    const scale = allowed / length;
+    return { x: pivot.x + dx * scale, y: pivot.y + dy * scale, z: pivot.z + dz * scale };
+}
 /**
  * Drift-lag (#1051): the yaw the chase anchor should aim before temporal
  * smoothing. When the target slides, its planar `velocity` diverges from its

package/dist/defineGame.d.ts

@@ -1,5 +1,7 @@
 import { type ComponentType } from "react";
+import type { EditorDocument } from "@jgengine/core/editor/types";
 import { type GameDefinitionConfig, type GameLoop } from "@jgengine/core/game/defineGame";
+import type { BackdropConfig } from "@jgengine/core/game/playableGame";
 import type { GameContext, GameContextContent } from "@jgengine/core/runtime/gameContext";
 import type { ModelAssetRef } from "@jgengine/core/scene/assetCatalog";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
@@ -19,6 +21,13 @@ type PresentationFields = Omit<PlayableGame, "game" | "content" | "loop" | "Game
     sceneScatterModels?: Record<string, string | ModelConfig>;
 };
 export type GameConfig<TAssetRef extends ModelAssetRef = ModelAssetRef> = EngineFields<TAssetRef> & PresentationFields;
+/**
+ * The scene document's authored sky fills `backdrop.sky` when the game did not set one, so editor
+ * lighting-workspace edits render in `place()` worlds too. A document environment carrying only
+ * point lights yields no sky fields and leaves the world's sky alone.
+ * @internal
+ */
+export declare function withDocumentSky(backdrop: BackdropConfig | undefined, doc: EditorDocument | undefined): BackdropConfig | undefined;
 /**
  * The one public authoring entry point: compose engine fields (systems, world, physics, input) and
  * presentation fields (camera, HUD, audio, authored scene) into a `PlayableGame` ready for `GameHost`.

package/dist/defineGame.js

@@ -3,6 +3,8 @@ import { useMemo } from "react";
 import { defineGameDefinition as defineEngineGame, } from "@jgengine/core/game/defineGame";
 import { syncLifecyclePhase } from "@jgengine/core/game/gamePhase";
 import { offline } from "@jgengine/core/runtime/adapter";
+import { lightingFromDocument, skyFromDocument } from "@jgengine/core/editor/environment";
+import { resolveGameLook } from "@jgengine/core/render/lookPreset";
 import { EnvironmentScene } from "./environment.js";
 import { terrainGroundColorSampler } from "./environment/terrainGroundColor.js";
 import { AuthoredScene } from "./scene/AuthoredScene.js";
@@ -12,6 +14,23 @@ function worldBackdrop(feature) {
         return _jsx(EnvironmentScene, { feature: feature });
     };
 }
+/**
+ * The scene document's authored sky fills `backdrop.sky` when the game did not set one, so editor
+ * lighting-workspace edits render in `place()` worlds too. A document environment carrying only
+ * point lights yields no sky fields and leaves the world's sky alone.
+ * @internal
+ */
+export function withDocumentSky(backdrop, doc) {
+    if (backdrop?.sky !== undefined || doc === undefined)
+        return backdrop;
+    const sky = skyFromDocument(doc);
+    if (sky === undefined || Object.keys(sky).length === 0)
+        return backdrop;
+    return { ...backdrop, sky };
+}
+function isEnvironmentSource(value) {
+    return typeof value === "object" && value !== null && "kind" in value && ["gradient", "hdri", "cube"].includes(value.kind);
+}
 function authoredSceneOverlay(document, placement, scatterModels, assets, world, Vfx) {
     const terrain = world !== undefined && world.kind === "environment" ? world.terrain : undefined;
     return function AuthoredSceneOverlay(props) {
@@ -28,12 +47,19 @@ const emptyUi = () => null;
  * @capability define-game single public game-authoring path — compose systems, world, presentation, and authored scene in one definition
  */
 export function defineGame(config) {
-    const { content, loop, GameUI, environment, camera, multiplayer, editorLayers, editorCatalogs, scenePlacement, sceneScatterModels, WorldOverlay, viewmodel, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, orientation, worldHealthBars, nameplates, presentationEffects, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting, backdrop, postProcessing, shadows, presentation, objectStyles, devtools, capture, platforms, hudFit, ...engineFields } = config;
+    const { content, loop, GameUI, environment, camera, multiplayer, editorLayers, editorCatalogs, scenePlacement, sceneScatterModels, WorldOverlay, viewmodel, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, gamepad, localPlayers, viewports, orientation, worldHealthBars, nameplates, presentationEffects, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting: authoredLighting, environmentSource, backdrop, look, postProcessing, shadows, graphics, presentation, objectStyles, devtools, capture, platforms, hudFit, ...engineFields } = config;
     const game = defineEngineGame({
         ...engineFields,
         multiplayer: multiplayer ?? offline(),
         loop,
     });
+    const resolvedLook = resolveGameLook({
+        look,
+        lighting: authoredLighting,
+        backdrop: withDocumentSky(backdrop, editorLayers),
+        postProcessing,
+        hasWorldSky: editorLayers?.environment?.preset !== undefined,
+    });
     function withPhaseSync(inner) {
         return (ctx, ...args) => {
             inner?.(ctx, ...args);
@@ -53,8 +79,9 @@ export function defineGame(config) {
             onDispose: composed?.onDispose?.bind(composed) ?? noop,
         },
         GameUI: GameUI ?? emptyUi,
-        environment: environment ??
-            (game.world?.kind === "environment" ? worldBackdrop(game.world) : undefined),
+        environment: isEnvironmentSource(environment) ? undefined :
+            environment ??
+                (game.world?.kind === "environment" ? worldBackdrop(game.world) : undefined),
         camera: camera ?? { perspective: "third" },
         editorLayers,
         editorCatalogs,
@@ -71,6 +98,9 @@ export function defineGame(config) {
         prompts,
         pointer,
         touch,
+        gamepad,
+        localPlayers,
+        viewports,
         orientation,
         worldHealthBars,
         nameplates,
@@ -81,10 +111,12 @@ export function defineGame(config) {
         worldItem,
         collision,
         movement,
-        lighting,
-        backdrop,
-        postProcessing,
+        lighting: resolvedLook.lighting ?? (editorLayers === undefined ? undefined : lightingFromDocument(editorLayers) ?? (editorLayers.environment?.pointLights === undefined ? undefined : { point: editorLayers.environment.pointLights })),
+        environmentSource: environmentSource ?? (isEnvironmentSource(environment) ? environment : undefined),
+        backdrop: resolvedLook.backdrop,
+        postProcessing: resolvedLook.postProcessing,
         shadows,
+        graphics,
         presentation,
         objectStyles,
         devtools,

package/dist/devtools/DevtoolsOverlay.js

@@ -5,6 +5,7 @@ import { devtools, instrumentLatency, } from "@jgengine/core/devtools/devtools";
 import { fallbackSeamsSnapshot } from "@jgengine/core/devtools/fallbackSeams";
 import { textureErrorsSnapshot } from "@jgengine/core/devtools/textureErrors";
 import { MOVEMENT_TUNING } from "@jgengine/core/movement/movementModel";
+import { heavyModels } from "../render/modelLoad.js";
 import { collisionDebug } from "./collisionDebug.js";
 import { readStoredOverrides } from "./devtoolsOverrides.js";
 import { diagnose } from "./perfDiagnose.js";
@@ -212,6 +213,7 @@ export function DevtoolsOverlay({ open, ctx, playable, multiplayer, }) {
             devtools.probes.register("objects", () => ctx.scene.object.list().length),
             devtools.probes.register("fallbacks", () => fallbackSeamsSnapshot()),
             devtools.probes.register("textureErrors", () => textureErrorsSnapshot()),
+            devtools.probes.register("heavyModels", () => heavyModels()),
         ];
         return () => {
             for (const dispose of disposers)

package/dist/devtools/KeysPanel.js

@@ -2,15 +2,15 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { bindingLabel } from "@jgengine/core/input/actionBindings";
 function flattenCodes(codes) {
     if (Array.isArray(codes)) {
-        return [{ codes: codes.map(bindingLabel).join(" / "), mode: "press" }];
+        return [{ codes: codes.map((code) => bindingLabel(code)).join(" / "), mode: "press" }];
     }
     const modes = codes;
     const result = [];
     if (modes.hold !== undefined && modes.hold.length > 0) {
-        result.push({ codes: modes.hold.map(bindingLabel).join(" / "), mode: "hold" });
+        result.push({ codes: modes.hold.map((code) => bindingLabel(code)).join(" / "), mode: "hold" });
     }
     if (modes.toggle !== undefined && modes.toggle.length > 0) {
-        result.push({ codes: modes.toggle.map(bindingLabel).join(" / "), mode: "toggle" });
+        result.push({ codes: modes.toggle.map((code) => bindingLabel(code)).join(" / "), mode: "toggle" });
     }
     return result;
 }

package/dist/devtools/agentBridge.d.ts

@@ -15,6 +15,12 @@ type EditorHost = {
     gameId: string;
     handle(request: AgentBridgeRequest): unknown;
 };
+/**
+ * @internal
+ * Resolves true once `isLive()` reports a mounted editor host, polling every `intervalMs` up to
+ * `timeoutMs`. `editor_summon` awaits this so the next RPC verb in a `drive` batch finds the editor.
+ */
+export declare function waitForEditorHost(isLive: () => boolean, timeoutMs?: number, intervalMs?: number, sleep?: (ms: number) => Promise<void>): Promise<boolean>;
 declare global {
     interface Window {
         __jgengineAgent?: {

package/dist/devtools/agentBridge.js

@@ -3,6 +3,20 @@ import { getSaveEndpoint } from "@jgengine/core/devtools/saveEndpoint";
 import { isHudAnchor, listActiveHudLayouts, } from "@jgengine/core/ui/hudLayout";
 import { listHudPanelTypes, resolvePanelResize, resizePanelSize, } from "@jgengine/core/ui/hudDocument";
 import { buildFullReport, buildLeanReport } from "./DevtoolsOverlay.js";
+/**
+ * @internal
+ * Resolves true once `isLive()` reports a mounted editor host, polling every `intervalMs` up to
+ * `timeoutMs`. `editor_summon` awaits this so the next RPC verb in a `drive` batch finds the editor.
+ */
+export async function waitForEditorHost(isLive, timeoutMs = 15_000, intervalMs = 100, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+    for (let waited = 0;; waited += intervalMs) {
+        if (isLive())
+            return true;
+        if (waited >= timeoutMs)
+            return false;
+        await sleep(intervalMs);
+    }
+}
 async function saveScene(editorHost) {
     const endpoint = getSaveEndpoint();
     if (endpoint === null)
@@ -239,7 +253,7 @@ export function installAgentBridge(options) {
                     return { ok: false, error: "no editor summoner on this page — open with ?mode=editor" };
                 }
                 window.__jgengineSummonEditor();
-                return { ok: true, live: false };
+                return waitForEditorHost(() => window.__jgengineEditorHost !== undefined).then((live) => live ? { ok: true, live: true } : { ok: false, error: "editor did not mount within 15s" });
             }
             case "save_scene": {
                 const editorHost = window.__jgengineEditorHost;

package/dist/diagnostics/FpsCounter.d.ts

@@ -0,0 +1,17 @@
+import { type ReactElement } from "react";
+/** Mutable frame tally shared between the in-Canvas probe and the DOM readout. */
+export interface FrameTally {
+    frames: number;
+}
+/** Counts rendered frames. Mount inside the Canvas. @internal */
+export declare function FpsProbe({ tally }: {
+    tally: FrameTally;
+}): null;
+/**
+ * Player-facing frames-per-second readout, sampled twice a second from rendered frames (not
+ * display refreshes), so it reflects the frame-rate limit and GPU load.
+ * @internal shell-internal; shown by the `graphics.showFps` setting.
+ */
+export declare function FpsCounter({ tally }: {
+    tally: FrameTally;
+}): ReactElement;

package/dist/diagnostics/FpsCounter.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useRef } from "react";
+/** Counts rendered frames. Mount inside the Canvas. @internal */
+export function FpsProbe({ tally }) {
+    useFrame(() => {
+        tally.frames += 1;
+    });
+    return null;
+}
+/**
+ * Player-facing frames-per-second readout, sampled twice a second from rendered frames (not
+ * display refreshes), so it reflects the frame-rate limit and GPU load.
+ * @internal shell-internal; shown by the `graphics.showFps` setting.
+ */
+export function FpsCounter({ tally }) {
+    const label = useRef(null);
+    useEffect(() => {
+        let last = performance.now();
+        tally.frames = 0;
+        const timer = setInterval(() => {
+            const now = performance.now();
+            const fps = (tally.frames * 1000) / Math.max(1, now - last);
+            tally.frames = 0;
+            last = now;
+            if (label.current !== null)
+                label.current.textContent = `${fps < 10 ? fps.toFixed(1) : Math.round(fps)} FPS`;
+        }, 500);
+        return () => clearInterval(timer);
+    }, [tally]);
+    return (_jsx("div", { className: "pointer-events-none absolute bottom-1 right-1 z-50 rounded bg-black/60 px-2 py-0.5 font-mono text-xs tabular-nums text-emerald-300", children: _jsx("span", { ref: label, children: "-- FPS" }) }));
+}

package/dist/drivers/FrameDriver.d.ts

@@ -4,8 +4,9 @@ import type { ActionStateTracker } from "@jgengine/core/input/actionBindings";
 import type { PointerService } from "../pointer/pointerService.js";
 import type { ShellMultiplayer } from "../multiplayer.js";
 import type { PlayableGame } from "../registry.js";
+import type { AuthoritativeFrameHandler } from "../worldSync.js";
 export declare const POSTER_SETTLE_SECONDS = 1.6;
-export declare function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryClickRef, pointerAxisRef, analogRef, gateRef, onRuntimeError, multiplayer, serverIdRef, pointerService, pointerAim, pingCommand, poster, onPosterSettled, }: {
+export declare function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryClickRef, pointerAxisRef, analogRef, gateRef, onRuntimeError, multiplayer, serverIdRef, pointerService, pointerAim, pingCommand, poster, onPosterSettled, authoritativeFrameRef, }: {
     ctx: GameContext;
     playable: PlayableGame;
     tracker: ActionStateTracker<string>;
@@ -37,4 +38,7 @@ export declare function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef,
     pingCommand: string | undefined;
     poster: boolean;
     onPosterSettled: () => void;
+    authoritativeFrameRef: {
+        current: AuthoritativeFrameHandler | null;
+    };
 }): null;