@jgengine/shell 0.18.1 → 0.21.0

package/dist/combat/ProjectileModels.d.ts

@@ -0,0 +1,31 @@
+import { type ReactElement } from "react";
+import * as THREE from "three";
+import type { LiveProjectile } from "@jgengine/core/combat/projectiles";
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+/** Explicit opt-in shaft/head geometry when a game has no projectile model. */
+export interface ProjectileShaft {
+    length?: number;
+    radius?: number;
+    shaftColor?: THREE.ColorRepresentation;
+    headColor?: THREE.ColorRepresentation;
+}
+/** Render simulated flights without owning their travel or settlement. */
+export interface ProjectileModelsProps {
+    model?: ModelConfig | ((projectile: LiveProjectile) => ModelConfig | undefined);
+    /** Defaults to no fallback geometry. */
+    fallback?: ProjectileShaft;
+    /** The model's nose axis. Default +Y, matching the shaft fallback. */
+    forward?: readonly [number, number, number];
+    maxInstances?: number;
+    /** An alternate authoritative source; otherwise uses the context's live flights. */
+    source?: () => readonly LiveProjectile[];
+}
+/** @internal Apply live position and full velocity orientation without frame allocations. */
+export declare function applyProjectilePose(group: THREE.Group, projectile: Pick<LiveProjectile, "position" | "velocity">, forward: THREE.Vector3, direction: THREE.Vector3): void;
+/**
+ * Mount caller-owned models at authoritative projectile positions. Flight ids
+ * determine lifetime; each frame only updates transforms, and settlement removes
+ * the model. Optional shaft/head geometry is enabled only by the caller.
+ * @capability projectile-models render authoritative projectile flights with caller models or opt-in shaft/head geometry, velocity orientation, bounded instances, and settlement cleanup
+ */
+export declare function ProjectileModels({ model, fallback, forward, maxInstances, source }: ProjectileModelsProps): ReactElement;

package/dist/combat/ProjectileModels.js

@@ -0,0 +1,70 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useRef, useState } from "react";
+import * as THREE from "three";
+import { useGameContext } from "@jgengine/react/provider";
+import { IsolatedEntityModel } from "../render/SceneModels.js";
+/** @internal Apply live position and full velocity orientation without frame allocations. */
+export function applyProjectilePose(group, projectile, forward, direction) {
+    group.position.set(...projectile.position);
+    direction.set(...projectile.velocity);
+    if (direction.lengthSq() > 1e-12)
+        group.quaternion.setFromUnitVectors(forward, direction.normalize());
+}
+function Shaft({ length = 0.85, radius = 0.012, shaftColor = "#947044", headColor = "#b9c4d0" }) {
+    const headLength = length * 0.18;
+    return _jsxs(_Fragment, { children: [_jsxs("mesh", { position: [0, -(length + headLength) / 2, 0], children: [_jsx("cylinderGeometry", { args: [radius, radius, length - headLength, 6] }), _jsx("meshStandardMaterial", { color: shaftColor, roughness: 0.78 })] }), _jsxs("mesh", { position: [0, -headLength / 2, 0], children: [_jsx("coneGeometry", { args: [radius * 3.5, headLength, 6] }), _jsx("meshStandardMaterial", { color: headColor, metalness: 0.5, roughness: 0.38 })] })] });
+}
+/**
+ * Mount caller-owned models at authoritative projectile positions. Flight ids
+ * determine lifetime; each frame only updates transforms, and settlement removes
+ * the model. Optional shaft/head geometry is enabled only by the caller.
+ * @capability projectile-models render authoritative projectile flights with caller models or opt-in shaft/head geometry, velocity orientation, bounded instances, and settlement cleanup
+ */
+export function ProjectileModels({ model, fallback, forward = [0, 1, 0], maxInstances = 256, source }) {
+    const ctx = useGameContext();
+    const entries = useRef(new Map());
+    const seen = useRef(new Set());
+    const direction = useRef(new THREE.Vector3());
+    const nose = useRef(new THREE.Vector3());
+    const [, setGeneration] = useState(0);
+    nose.current.set(...forward).normalize();
+    if (nose.current.lengthSq() === 0)
+        nose.current.set(0, 1, 0);
+    const limit = Number.isFinite(maxInstances) ? Math.max(0, Math.min(1024, Math.floor(maxInstances))) : 256;
+    useFrame(() => {
+        let changed = false;
+        const live = source?.() ?? ctx.scene.entity.activeProjectiles();
+        seen.current.clear();
+        for (let i = 0, n = Math.min(limit, live.length); i < n; i++) {
+            const flight = live[i];
+            const key = `${flight.shotId}:${flight.pellet}`;
+            seen.current.add(key);
+            const current = entries.current.get(key);
+            if (current === undefined) {
+                entries.current.set(key, { flight, group: null });
+                changed = true;
+            }
+            else {
+                current.flight = flight;
+                if (current.group !== null)
+                    applyProjectilePose(current.group, flight, nose.current, direction.current);
+            }
+        }
+        for (const key of entries.current.keys())
+            if (!seen.current.has(key)) {
+                entries.current.delete(key);
+                changed = true;
+            }
+        if (changed)
+            setGeneration((n) => n + 1);
+    });
+    return _jsx(_Fragment, { children: Array.from(entries.current, ([key, entry]) => {
+            const selected = typeof model === "function" ? model(entry.flight) : model;
+            return _jsx("group", { ref: (group) => {
+                    entry.group = group;
+                    if (group !== null)
+                        applyProjectilePose(group, entry.flight, nose.current, direction.current);
+                }, children: selected === undefined ? fallback === undefined ? null : _jsx(Shaft, { ...fallback }) : _jsx(IsolatedEntityModel, { model: selected, instanceId: key }) }, key);
+        }) });
+}

package/dist/commandSink.d.ts

@@ -14,8 +14,7 @@ export declare function localCommandSink(ctx: GameContext): CommandSink;
 export declare function remoteCommandSink(backend: Pick<LiveGameBackend, "transport">, serverId: string): CommandSink;
 /**
  * The sink a server-authoritative shell should dispatch gameplay commands through: remote when the game opts into
- * `authority: "server"` and a server is joined, local otherwise. Client-only UI commands (targeting, hotbar
- * scroll) keep calling `ctx.game.commands.run` directly — only authoritative gameplay verbs route to the host.
+ * `authority: "server"` and a server is joined. Before join it discards commands rather than mutating a replica.
   * @internal
   */
 export declare function resolveCommandSink(ctx: GameContext, opts: {

package/dist/commandSink.js

@@ -20,13 +20,14 @@ export function remoteCommandSink(backend, serverId) {
 }
 /**
  * The sink a server-authoritative shell should dispatch gameplay commands through: remote when the game opts into
- * `authority: "server"` and a server is joined, local otherwise. Client-only UI commands (targeting, hotbar
- * scroll) keep calling `ctx.game.commands.run` directly — only authoritative gameplay verbs route to the host.
+ * `authority: "server"` and a server is joined. Before join it discards commands rather than mutating a replica.
   * @internal
   */
 export function resolveCommandSink(ctx, opts) {
     if (opts.serverAuthoritative && opts.backend !== null && opts.serverId !== null) {
         return remoteCommandSink(opts.backend, opts.serverId);
     }
+    if (opts.serverAuthoritative)
+        return { run() { } };
     return localCommandSink(ctx);
 }

package/dist/defineGame.d.ts

@@ -1,8 +1,12 @@
 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";
+import type { SkyEnvironmentConfig } from "@jgengine/core/world/features";
+import type { ResolveAuthoredObjectsOptions } from "@jgengine/core/world/authoredObjects";
 import type { PlayableGame } from "./registry.js";
 type EngineFields<TAssetRef extends ModelAssetRef> = Omit<GameDefinitionConfig<TAssetRef>, "loop" | "ui" | "multiplayer"> & {
     multiplayer?: GameDefinitionConfig<TAssetRef>["multiplayer"];
@@ -11,14 +15,26 @@ type PresentationFields = Omit<PlayableGame, "game" | "content" | "loop" | "Game
     content?: GameContextContent;
     loop?: Partial<GameLoop<GameContext>>;
     GameUI?: ComponentType;
-    /** Tunes how the auto-mounted `AuthoredScene` places the document's catalog-id markers into the object store. Default `true`; pass `false` when the game spawns its placed content as entities itself (`placeAuthoredObjects`) to avoid a double render. */
-    scenePlacement?: boolean | {
+    /** Tunes how the auto-mounted `AuthoredScene` places catalog-id markers into the object store. Default `true`; `excludeKinds` replaces the resolver's mob/boss exclusions, so include those when adding game-owned spawn kinds. Pass `false` when the game places all content itself. */
+    scenePlacement?: boolean | ({
         verticalOffset?: number;
-    };
+    } & ResolveAuthoredObjectsOptions);
     /** GLB models for the auto-mounted scene's scatter palette items, keyed by palette item id; string ids resolve through the game's asset catalog. Unmatched items keep the built-in proxy meshes. */
     sceneScatterModels?: Record<string, string | ModelConfig>;
+    /** Animated species models for cosmetic authored habitats; gameplay actors remain game-owned. */
+    sceneFlockModels?: Record<string, string | ModelConfig>;
+    /** Visible ground path kinds; omit to draw every non-scatter path, or restrict to keep flight/patrol guides out of world roads. */
+    scenePathKinds?: readonly string[];
 };
 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. Defined document fields overlay the
+ * legacy world's sky, preserving settings the editor cannot represent. An 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, worldSky?: SkyEnvironmentConfig): 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,7 +3,7 @@ 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 } from "@jgengine/core/editor/environment";
+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";
@@ -14,14 +14,36 @@ 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. Defined document fields overlay the
+ * legacy world's sky, preserving settings the editor cannot represent. An environment carrying only
+ * point lights yields no sky fields and leaves the world's sky alone.
+ * @internal
+ */
+export function withDocumentSky(backdrop, doc, worldSky) {
+    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: {
+            ...worldSky,
+            ...sky,
+            ...(sky.sun === undefined ? {} : { sun: { ...worldSky?.sun,
+                    ...Object.fromEntries(Object.entries(sky.sun).filter(([, value]) => value !== undefined)) } }),
+            ...(sky.fog === undefined ? {} : { fog: { ...worldSky?.fog,
+                    ...Object.fromEntries(Object.entries(sky.fog).filter(([, value]) => value !== undefined)) } }),
+        } };
+}
 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) {
+function authoredSceneOverlay(document, diagnostics, placement, scatterModels, flockModels, pathKinds, assets, world, Vfx) {
     const terrain = world !== undefined && world.kind === "environment" ? world.terrain : undefined;
     return function AuthoredSceneOverlay(props) {
         const groundColorAt = useMemo(() => terrainGroundColorSampler(terrain, props.ctx.world.ground), [props.ctx.world.ground]);
-        return (_jsxs(_Fragment, { children: [_jsx(AuthoredScene, { document: document, field: props.ctx.world.ground, placeObjects: placement, ...(scatterModels === undefined ? {} : { scatterModels, assets }), ...(groundColorAt === undefined ? {} : { groundColorAt }) }), Vfx === undefined ? null : _jsx(Vfx, { ...props })] }));
+        return (_jsxs(_Fragment, { children: [_jsx(AuthoredScene, { document: document, diagnostics: diagnostics, field: props.ctx.world.ground, placeObjects: placement, assets: assets, ...(scatterModels === undefined ? {} : { scatterModels }), ...(flockModels === undefined ? {} : { flockModels }), ...(pathKinds === undefined ? {} : { pathKinds }), ...(groundColorAt === undefined ? {} : { groundColorAt }) }), Vfx === undefined ? null : _jsx(Vfx, { ...props })] }));
     };
 }
 const emptyUi = () => null;
@@ -33,16 +55,22 @@ 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: authoredLighting, environmentSource, backdrop, look, postProcessing, shadows, graphics, presentation, objectStyles, devtools, capture, platforms, hudFit, ...engineFields } = config;
+    const { content, loop, GameUI, environment, camera, multiplayer, editorLayers, editorCatalogs, scenePlacement, sceneScatterModels, sceneFlockModels, scenePathKinds, 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, settings, objectStyles, devtools, capture, platforms, hudFit, ...engineFields } = config;
     const game = defineEngineGame({
         ...engineFields,
+        ...(editorLayers === undefined ? {} : { authoredDocument: editorLayers }),
         multiplayer: multiplayer ?? offline(),
-        loop,
+        loop: { ...loop, onDispose(ctx) { try {
+                loop?.onDispose?.(ctx);
+            }
+            finally {
+                ctx.environment.dispose();
+            } } },
     });
     const resolvedLook = resolveGameLook({
         look,
         lighting: authoredLighting,
-        backdrop,
+        backdrop: withDocumentSky(backdrop, editorLayers, engineFields.world?.kind === "environment" ? engineFields.world.sky : undefined),
         postProcessing,
         hasWorldSky: editorLayers?.environment?.preset !== undefined,
     });
@@ -73,7 +101,7 @@ export function defineGame(config) {
         editorCatalogs,
         WorldOverlay: editorLayers === undefined
             ? WorldOverlay
-            : authoredSceneOverlay(editorLayers, scenePlacement ?? true, sceneScatterModels, game.assets, game.world, WorldOverlay),
+            : authoredSceneOverlay(editorLayers, devtools !== false, scenePlacement ?? true, sceneScatterModels, sceneFlockModels, scenePathKinds, game.assets, game.world, WorldOverlay),
         viewmodel,
         renderEntity,
         renderObject,
@@ -84,6 +112,9 @@ export function defineGame(config) {
         prompts,
         pointer,
         touch,
+        gamepad,
+        localPlayers,
+        viewports,
         orientation,
         worldHealthBars,
         nameplates,
@@ -101,6 +132,7 @@ export function defineGame(config) {
         shadows,
         graphics,
         presentation,
+        settings,
         objectStyles,
         devtools,
         capture,

package/dist/devtools/DevtoolsOverlay.d.ts

@@ -1,78 +1,11 @@
-import { type DevtoolsSnapshot } from "@jgengine/core/devtools/devtools";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
 import type { ShellMultiplayer } from "../multiplayer.js";
 import type { PlayableGame } from "../registry.js";
 export { applyStoredDevtoolsOverrides, persistDevtoolsOverrides } from "./devtoolsOverrides.js";
-/** @internal */
-export declare function withDevtoolsLatency(multiplayer: ShellMultiplayer): ShellMultiplayer;
+export { withDevtoolsLatency } from "./latencyInstrumentation.js";
 /** @internal */
 export declare function DevtoolsRendererProbe(): null;
-/** @internal */
-export declare function buildLeanReport(playable: PlayableGame): {
-    game: string;
-    at: number;
-    why: string | null;
-    frame: {
-        fps: number;
-        avgFrameMs: number;
-        p95FrameMs: number;
-        maxFrameMs: number;
-        avgSimMs: number;
-        maxSimMs: number;
-        avgOutsideMs: number;
-        maxOutsideMs: number;
-        longFrames: number;
-        samples: number;
-        phases: {
-            name: string;
-            avgMs: number;
-            maxMs: number;
-            pctOfSim: number;
-        }[];
-    } | null;
-    render: import("@jgengine/core/devtools/types").RenderSample | null;
-    latency: import("@jgengine/core/devtools/types").LatencyStats | null;
-    longFrameSummary: {
-        count: number;
-        culprits: {
-            culprit: string;
-            count: number;
-        }[];
-        maxFrameMs: number;
-        maxDrawCalls: number | undefined;
-        maxGeometries: number | undefined;
-    } | null;
-    longFrames: {
-        at: number;
-        frameMs: number;
-        simMs: number;
-        outsideMs: number;
-        culprit: string;
-        reason: string;
-        phases: {
-            name: string;
-            ms: number;
-        }[];
-        probes: Record<string, unknown>;
-        render: import("@jgengine/core/devtools/types").RenderSample | null;
-    }[];
-    probes: Record<string, unknown>;
-    logs: import("@jgengine/core/devtools/types").DevtoolsLogEntry[] | undefined;
-    controls: {
-        name: string;
-        value: unknown;
-        initial: unknown;
-    }[] | undefined;
-    discovered: {
-        id: string;
-        value: unknown;
-    }[] | undefined;
-    discoveredCount: number;
-};
-/** @internal */
-export declare function buildFullReport(playable: PlayableGame): DevtoolsSnapshot & {
-    game: string;
-};
+export { buildLeanReport, buildFullReport } from "./devtoolsReports.js";
 /** @internal */
 export declare function DevtoolsOverlay({ open, ctx, playable, multiplayer, }: {
     open: boolean;

package/dist/devtools/DevtoolsOverlay.js

@@ -1,13 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef, useState, useSyncExternalStore } from "react";
-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 { collisionDebug } from "./collisionDebug.js";
-import { readStoredOverrides } from "./devtoolsOverrides.js";
-import { diagnose } from "./perfDiagnose.js";
+import { devtools, } from "@jgengine/core/devtools/devtools";
+import { heavyModels } from "../render/modelLoad.js";
+import { buildLeanReport } from "./devtoolsReports.js";
 import { PerfPanel } from "./PerfPanel.js";
 import { LogsPanel } from "./LogsPanel.js";
 import { NetPanel } from "./NetPanel.js";
@@ -16,20 +12,12 @@ import { ColPanel } from "./ColPanel.js";
 import { TunePanel } from "./TunePanel.js";
 export { applyStoredDevtoolsOverrides, persistDevtoolsOverrides } from "./devtoolsOverrides.js";
 const REFRESH_MS = 250;
-/** @internal */
-export function withDevtoolsLatency(multiplayer) {
-    return {
-        ...multiplayer,
-        backend: {
-            ...instrumentLatency(multiplayer.backend, ["pushFeedEntry"]),
-            transport: instrumentLatency(multiplayer.backend.transport, ["joinServer", "leaveServer", "runCommand"]),
-        },
-    };
-}
+export { withDevtoolsLatency } from "./latencyInstrumentation.js";
 const RENDER_SAMPLE_MS = 500;
 const RENDER_PROBE_FRAME_PRIORITY = -10;
 /** @internal */
 export function DevtoolsRendererProbe() {
+    useEffect(() => devtools.probes.register("heavyModels", () => heavyModels()), []);
     const gl = useThree((state) => state.gl);
     const lastSampleAt = useRef(0);
     useEffect(() => {
@@ -65,165 +53,25 @@ const TABS = [
     { id: "net", label: "Net" },
     { id: "keys", label: "Keys" },
 ];
-function roundMs(value, digits = 1) {
-    const scale = 10 ** digits;
-    return Math.round(value * scale) / scale;
-}
-function compactLongFrame(event) {
-    return {
-        at: event.at,
-        frameMs: roundMs(event.frameMs),
-        simMs: roundMs(event.simMs),
-        outsideMs: roundMs(event.outsideMs),
-        culprit: event.culprit,
-        reason: event.reason,
-        phases: event.phases.slice(0, 4).map((phase) => ({
-            name: phase.name,
-            ms: roundMs(phase.ms),
-        })),
-        probes: event.probes,
-        render: event.render,
-    };
-}
-function summarizeLongFrames(events) {
-    if (events.length === 0)
-        return null;
-    const byCulprit = new Map();
-    let maxFrameMs = 0;
-    let maxDraws = 0;
-    let maxGeometries = 0;
-    for (const event of events) {
-        byCulprit.set(event.culprit, (byCulprit.get(event.culprit) ?? 0) + 1);
-        maxFrameMs = Math.max(maxFrameMs, event.frameMs);
-        if (event.render !== null) {
-            maxDraws = Math.max(maxDraws, event.render.drawCalls);
-            maxGeometries = Math.max(maxGeometries, event.render.geometries);
-        }
-    }
-    const culprits = [...byCulprit.entries()]
-        .sort((a, b) => b[1] - a[1])
-        .map(([culprit, count]) => ({ culprit, count }));
-    return {
-        count: events.length,
-        culprits,
-        maxFrameMs: roundMs(maxFrameMs),
-        maxDrawCalls: maxDraws > 0 ? maxDraws : undefined,
-        maxGeometries: maxGeometries > 0 ? maxGeometries : undefined,
-    };
-}
-/** @internal */
-export function buildLeanReport(playable) {
-    const snap = devtools.snapshot();
-    const frame = snap.frame;
-    const longs = snap.longFrames;
-    const why = frame !== null ? diagnose(frame, longs) : null;
-    const changedControls = snap.controls
-        .filter((control) => !Object.is(control.value, control.initial))
-        .map((control) => ({ name: control.name, value: control.value, initial: control.initial }));
-    const enabledDiscovered = snap.discovered
-        .filter((entry) => entry.enabled)
-        .map((entry) => ({ id: entry.id, value: entry.value }));
-    const hotLogs = snap.logs.filter((entry) => entry.level === "warn" || entry.level === "error").slice(-20);
-    return {
-        game: playable.game.name,
-        at: snap.at,
-        why,
-        frame: frame === null
-            ? null
-            : {
-                fps: roundMs(frame.fps, 1),
-                avgFrameMs: roundMs(frame.avgFrameMs),
-                p95FrameMs: roundMs(frame.p95FrameMs),
-                maxFrameMs: roundMs(frame.maxFrameMs),
-                avgSimMs: roundMs(frame.avgSimMs),
-                maxSimMs: roundMs(frame.maxSimMs),
-                avgOutsideMs: roundMs(frame.avgOutsideMs),
-                maxOutsideMs: roundMs(frame.maxOutsideMs),
-                longFrames: frame.longFrames,
-                samples: frame.samples,
-                phases: frame.phases.slice(0, 8).map((phase) => ({
-                    name: phase.name,
-                    avgMs: roundMs(phase.avgMs),
-                    maxMs: roundMs(phase.maxMs),
-                    pctOfSim: Math.round(phase.pctOfSim),
-                })),
-            },
-        render: snap.render,
-        latency: snap.latency,
-        longFrameSummary: summarizeLongFrames(longs),
-        longFrames: longs.slice(-6).map(compactLongFrame),
-        probes: snap.probes,
-        logs: hotLogs.length > 0 ? hotLogs : undefined,
-        controls: changedControls.length > 0 ? changedControls : undefined,
-        discovered: enabledDiscovered.length > 0 ? enabledDiscovered : undefined,
-        discoveredCount: snap.discovered.length,
-    };
-}
-/** @internal */
-export function buildFullReport(playable) {
-    return { game: playable.game.name, ...devtools.snapshot() };
-}
+export { buildLeanReport, buildFullReport } from "./devtoolsReports.js";
 /** @internal */
 export function DevtoolsOverlay({ open, ctx, playable, multiplayer, }) {
     const [tab, setTab] = useState("perf");
     const [, setTick] = useState(0);
     const [copied, setCopied] = useState(false);
     useSyncExternalStore(devtools.signal.subscribe, devtools.signal.version, devtools.signal.version);
-    useEffect(() => {
-        devtools.logs.captureConsole();
-        globalThis.__JG_DEVTOOLS = {
-            snapshot: () => buildLeanReport(playable),
-            snapshotFull: () => buildFullReport(playable),
-            controls: devtools.controls,
-            discover: devtools.discover,
-            frame: devtools.frame,
-            profile: devtools.profile,
-            collisionDebug,
-        };
-    }, [playable]);
-    useEffect(() => {
-        devtools.discover.scanTable("game", playable);
-        devtools.discover.scanTable("engine", { movement: MOVEMENT_TUNING });
-    }, [playable]);
-    useEffect(() => {
-        const stored = readStoredOverrides(playable.game.name);
-        if (stored === null)
-            return;
-        const appliedEnables = new Set();
-        const appliedValues = new Set();
-        const applyLateRegistrations = () => {
-            const discovered = new Map(devtools.discover.list().map((entry) => [entry.id, entry]));
-            const needEnable = stored.enabled.filter((id) => !appliedEnables.has(id) && discovered.get(id)?.enabled === false);
-            const needValue = Object.entries(stored.values).filter(([name]) => !appliedValues.has(name) && devtools.controls.get(name) !== null);
-            if (needEnable.length === 0 && needValue.length === 0)
-                return;
-            for (const id of needEnable)
-                appliedEnables.add(id);
-            for (const [name] of needValue)
-                appliedValues.add(name);
-            devtools.overrides.apply({ enabled: needEnable, values: Object.fromEntries(needValue) });
-        };
-        applyLateRegistrations();
-        return devtools.signal.subscribe(applyLateRegistrations);
-    }, [playable]);
-    useEffect(() => {
-        const disposers = [
-            devtools.probes.register("entities", () => ctx.scene.entity.list().length),
-            devtools.probes.register("objects", () => ctx.scene.object.list().length),
-            devtools.probes.register("fallbacks", () => fallbackSeamsSnapshot()),
-            devtools.probes.register("textureErrors", () => textureErrorsSnapshot()),
-        ];
-        return () => {
-            for (const dispose of disposers)
-                dispose();
-        };
-    }, [ctx]);
     useEffect(() => {
         if (!open)
             return;
-        const interval = setInterval(() => setTick((current) => current + 1), REFRESH_MS);
-        return () => clearInterval(interval);
-    }, [open]);
+        let lastRefresh = 0;
+        return ctx.subscribe(() => {
+            const now = performance.now();
+            if (now - lastRefresh < REFRESH_MS)
+                return;
+            lastRefresh = now;
+            setTick((current) => current + 1);
+        });
+    }, [ctx, open]);
     if (!open)
         return null;
     const copyReport = () => {

package/dist/devtools/DevtoolsRuntime.d.ts

@@ -0,0 +1,7 @@
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { PlayableGame } from "../registry.js";
+/** Keeps saved overrides and diagnostic registration live while the visual panel is closed. @internal */
+export declare function DevtoolsRuntime({ ctx, playable }: {
+    ctx: GameContext;
+    playable: PlayableGame;
+}): null;

package/dist/devtools/DevtoolsRuntime.js

@@ -0,0 +1,61 @@
+import { useEffect } from "react";
+import { devtools } 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 { collisionDebug } from "./collisionDebug.js";
+import { readStoredOverrides } from "./devtoolsOverrides.js";
+import { buildLeanReport, buildFullReport } from "./devtoolsReports.js";
+/** Keeps saved overrides and diagnostic registration live while the visual panel is closed. @internal */
+export function DevtoolsRuntime({ ctx, playable }) {
+    useEffect(() => {
+        devtools.logs.captureConsole();
+        globalThis.__JG_DEVTOOLS = {
+            snapshot: () => buildLeanReport(playable),
+            snapshotFull: () => buildFullReport(playable),
+            controls: devtools.controls,
+            discover: devtools.discover,
+            frame: devtools.frame,
+            profile: devtools.profile,
+            collisionDebug,
+        };
+    }, [playable]);
+    useEffect(() => {
+        devtools.discover.scanTable("game", playable);
+        devtools.discover.scanTable("engine", { movement: MOVEMENT_TUNING });
+    }, [playable]);
+    useEffect(() => {
+        const stored = readStoredOverrides(playable.game.name);
+        if (stored === null)
+            return;
+        const appliedEnables = new Set();
+        const appliedValues = new Set();
+        const applyLateRegistrations = () => {
+            const discovered = new Map(devtools.discover.list().map((entry) => [entry.id, entry]));
+            const needEnable = stored.enabled.filter((id) => !appliedEnables.has(id) && discovered.get(id)?.enabled === false);
+            const needValue = Object.entries(stored.values).filter(([name]) => !appliedValues.has(name) && devtools.controls.get(name) !== null);
+            if (needEnable.length === 0 && needValue.length === 0)
+                return;
+            for (const id of needEnable)
+                appliedEnables.add(id);
+            for (const [name] of needValue)
+                appliedValues.add(name);
+            devtools.overrides.apply({ enabled: needEnable, values: Object.fromEntries(needValue) });
+        };
+        applyLateRegistrations();
+        return devtools.signal.subscribe(applyLateRegistrations);
+    }, [playable]);
+    useEffect(() => {
+        const disposers = [
+            devtools.probes.register("entities", () => ctx.scene.entity.list().length),
+            devtools.probes.register("objects", () => ctx.scene.object.list().length),
+            devtools.probes.register("fallbacks", () => fallbackSeamsSnapshot()),
+            devtools.probes.register("textureErrors", () => textureErrorsSnapshot()),
+        ];
+        return () => {
+            for (const dispose of disposers)
+                dispose();
+        };
+    }, [ctx]);
+    return null;
+}

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?: {