@jgengine/shell 0.8.0 → 0.10.0

package/dist/devtools/DevtoolsOverlay.js

@@ -1,10 +1,22 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useFrame } from "@react-three/fiber";
 import { useEffect, useRef, useState, useSyncExternalStore } from "react";
-import { devtools, instrumentLatency, } from "@jgengine/core/devtools/devtools";
+import { convertAngle, devtools, instrumentLatency, LONG_FRAME_MS, parseColor, parseOverridesPayload, } from "@jgengine/core/devtools/devtools";
 import { bindingLabel } from "@jgengine/core/input/actionBindings";
+import { MOVEMENT_TUNING } from "@jgengine/core/movement/movementModel";
+import { COLLISION_DEBUG_LAYERS, collisionDebug, } from "./collisionDebug.js";
 const REFRESH_MS = 250;
-const LONG_FRAME_MS = 33.4;
+const PHASE_BAR_BUDGET_MS = 16.7;
+const CULPRIT_HINTS = {
+    "outside-sim": "Cost is outside the sim driver — three.js render, React commit, GPU, GC, or tab throttle.",
+    sim: "Sim is slow but no named phase stands out — wrap hot onTick work with measure(\"name\", fn).",
+    onTick: "Game loop.onTick is the hotspot — profile inside it with measure(\"physics\"|\"ai\"|…, fn).",
+    pose: "Shell movement / collision / voxel step is expensive.",
+    actions: "Input → command dispatch / hotbar / interact is expensive.",
+    presence: "Multiplayer pose sync is expensive.",
+    pickup: "Auto-pickup nearest scan is expensive.",
+    "time+input": "Clock advance or input publish is unexpectedly heavy.",
+};
 function overridesStorageKey(gameName) {
     return `jg-devtools:${gameName}`;
 }
@@ -13,8 +25,15 @@ function readStoredOverrides(gameName) {
         const raw = localStorage.getItem(overridesStorageKey(gameName));
         if (raw === null)
             return null;
-        const parsed = JSON.parse(raw);
-        return Array.isArray(parsed.enabled) && typeof parsed.values === "object" ? parsed : null;
+        const parsed = parseOverridesPayload(JSON.parse(raw));
+        if (parsed.overrides === null) {
+            for (const message of parsed.diagnostics)
+                console.warn(`[jgengine:devtools] ${message}`);
+            return null;
+        }
+        for (const message of parsed.diagnostics)
+            console.info(`[jgengine:devtools] ${message}`);
+        return parsed.overrides;
     }
     catch {
         return null;
@@ -34,11 +53,14 @@ export function applyStoredDevtoolsOverrides(gameName) {
     const stored = readStoredOverrides(gameName);
     if (stored === null)
         return;
-    const applied = stored.enabled.length + Object.keys(stored.values).length;
-    if (applied === 0)
+    const result = devtools.overrides.apply(stored);
+    if (result.applied === 0 && result.skipped.length === 0)
         return;
-    devtools.overrides.apply(stored);
-    console.info(`[jgengine:devtools] applied ${applied} stored override(s) for ${gameName}`);
+    console.info(`[jgengine:devtools] applied ${result.applied} stored override(s) for ${gameName}` +
+        (result.skipped.length > 0 ? ` · skipped ${result.skipped.length}` : ""));
+    for (const entry of result.skipped) {
+        console.warn(`[jgengine:devtools] skipped override ${entry.id}: ${entry.reason}`);
+    }
 }
 export function withDevtoolsLatency(multiplayer) {
     return {
@@ -91,6 +113,7 @@ function flattenCodes(codes) {
 const TABS = [
     { id: "perf", label: "Perf" },
     { id: "tune", label: "Tune" },
+    { id: "col", label: "Col" },
     { id: "logs", label: "Logs" },
     { id: "net", label: "Net" },
     { id: "keys", label: "Keys" },
@@ -102,12 +125,74 @@ function StatRow({ name, value, alert }) {
     return (_jsxs("div", { className: "flex items-baseline justify-between gap-3", children: [_jsx("span", { className: "text-neutral-400", children: name }), _jsx("span", { className: `font-mono ${alert === true ? "text-red-400" : "text-neutral-100"}`, children: value })] }));
 }
 function FrameBars({ frames }) {
-    return (_jsx("div", { className: "flex h-10 items-end gap-px", children: frames.map((frameMs, index) => (_jsx("div", { className: `w-1 rounded-sm ${frameMs > LONG_FRAME_MS ? "bg-red-500" : "bg-emerald-500/80"}`, style: { height: `${Math.min(100, (frameMs / (LONG_FRAME_MS * 2)) * 100)}%` } }, index))) }));
+    return (_jsx("div", { className: "flex h-10 items-end gap-px", children: frames.map((frameMs, index) => (_jsx("div", { className: `w-1 rounded-sm ${frameMs > LONG_FRAME_MS ? "bg-red-500" : "bg-emerald-500/80"}`, style: { height: `${Math.min(100, (frameMs / (LONG_FRAME_MS * 2)) * 100)}%` }, title: `${frameMs.toFixed(1)}ms` }, index))) }));
+}
+function SectionLabel({ children }) {
+    return _jsx("div", { className: "text-[9px] uppercase tracking-wide text-neutral-500", children: children });
+}
+function PhaseBars({ phases, avgSimMs }) {
+    if (phases.length === 0) {
+        return _jsx("div", { className: "text-neutral-500", children: "No phase samples yet." });
+    }
+    const budget = Math.max(PHASE_BAR_BUDGET_MS, avgSimMs, ...phases.map((phase) => phase.avgMs));
+    return (_jsx("div", { className: "space-y-1", children: phases.slice(0, 8).map((phase) => {
+            const hot = phase.avgMs > 4 || phase.maxMs > 8;
+            return (_jsxs("div", { className: "space-y-0.5", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-2", children: [_jsx("span", { className: `truncate ${hot ? "text-amber-300" : "text-neutral-300"}`, title: phase.name, children: phase.name }), _jsxs("span", { className: `shrink-0 font-mono ${hot ? "text-amber-300" : "text-neutral-100"}`, children: [ms(phase.avgMs), _jsx("span", { className: "text-neutral-500", children: " avg" }), _jsx("span", { className: "text-neutral-600", children: " \u00B7 " }), ms(phase.maxMs), _jsx("span", { className: "text-neutral-500", children: " max" }), _jsx("span", { className: "text-neutral-600", children: " \u00B7 " }), phase.pctOfSim.toFixed(0), "%"] })] }), _jsx("div", { className: "h-1.5 overflow-hidden rounded-full bg-neutral-800", children: _jsx("div", { className: `h-full rounded-full ${hot ? "bg-amber-400" : "bg-emerald-500/80"}`, style: { width: `${Math.min(100, (phase.avgMs / budget) * 100)}%` } }) })] }, phase.name));
+        }) }));
+}
+function BudgetSplit({ simMs, outsideMs }) {
+    const total = Math.max(1e-6, simMs + outsideMs);
+    const simPct = (simMs / total) * 100;
+    const outsideHot = outsideMs > simMs && outsideMs > 4;
+    const simHot = simMs > 8;
+    return (_jsxs("div", { className: "space-y-1", children: [_jsxs("div", { className: "flex h-2 overflow-hidden rounded-full bg-neutral-800", children: [_jsx("div", { className: `h-full ${simHot ? "bg-amber-400" : "bg-sky-400"}`, style: { width: `${simPct}%` }, title: `sim ${ms(simMs)}` }), _jsx("div", { className: `h-full ${outsideHot ? "bg-red-500" : "bg-violet-400/80"}`, style: { width: `${100 - simPct}%` }, title: `outside sim ${ms(outsideMs)}` })] }), _jsxs("div", { className: "flex justify-between gap-2 font-mono text-[10px]", children: [_jsxs("span", { className: simHot ? "text-amber-300" : "text-sky-300", children: ["sim ", ms(simMs)] }), _jsxs("span", { className: outsideHot ? "text-red-400" : "text-violet-300", children: ["outside ", ms(outsideMs)] })] }), _jsx("div", { className: "text-[10px] text-neutral-500", children: "outside = render / React / GPU / GC / missed vsync \u2014 not measured inside the sim driver" })] }));
+}
+function diagnose(frame, longs) {
+    if (frame.fps >= 55 && frame.longFrames === 0 && longs.length === 0)
+        return null;
+    const recent = longs.slice(-5);
+    const culpritCounts = new Map();
+    for (const event of recent) {
+        culpritCounts.set(event.culprit, (culpritCounts.get(event.culprit) ?? 0) + 1);
+    }
+    let topCulprit = null;
+    let topCount = 0;
+    for (const [name, count] of culpritCounts) {
+        if (count > topCount) {
+            topCulprit = name;
+            topCount = count;
+        }
+    }
+    if (topCulprit === null && frame.phases[0] !== undefined && frame.avgSimMs > 8) {
+        topCulprit = frame.phases[0].name;
+    }
+    if (topCulprit === null && frame.avgOutsideMs > frame.avgSimMs && frame.avgOutsideMs > 4) {
+        topCulprit = "outside-sim";
+    }
+    if (topCulprit === null) {
+        if (frame.p95FrameMs > LONG_FRAME_MS)
+            return `p95 ${ms(frame.p95FrameMs)} — hitching without a clear phase; check long-frame log as it fills.`;
+        return null;
+    }
+    const hint = CULPRIT_HINTS[topCulprit] ?? `Hotspot “${topCulprit}” — dig into that phase with measure() or reduce its work.`;
+    const countText = topCount > 0 ? ` (${topCount}/${recent.length || topCount} recent long frames)` : "";
+    return `${topCulprit}${countText}: ${hint}`;
+}
+function LongFrameList({ events }) {
+    if (events.length === 0) {
+        return _jsxs("div", { className: "text-neutral-500", children: ["No long frames (>", ms(LONG_FRAME_MS), ") captured yet."] });
+    }
+    const newest = [...events].reverse().slice(0, 12);
+    return (_jsx("div", { className: "jg-devtools-scroll max-h-40 space-y-1.5 overflow-auto", children: newest.map((event, index) => (_jsxs("div", { className: "rounded border border-neutral-800 bg-neutral-900/60 px-1.5 py-1", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-2", children: [_jsx("span", { className: "font-mono text-red-400", children: ms(event.frameMs) }), _jsx("span", { className: "truncate text-amber-300", title: event.culprit, children: event.culprit }), _jsx("span", { className: "shrink-0 text-neutral-500", children: new Date(event.at).toLocaleTimeString() })] }), _jsx("div", { className: "mt-0.5 text-[10px] leading-snug text-neutral-300", children: event.reason }), event.phases.length > 0 ? (_jsxs("div", { className: "mt-0.5 font-mono text-[9px] text-neutral-500", children: [event.phases
+                            .slice(0, 4)
+                            .map((phase) => `${phase.name} ${phase.ms.toFixed(1)}`)
+                            .join(" · "), event.outsideMs >= 2 ? ` · outside ${event.outsideMs.toFixed(1)}` : ""] })) : event.outsideMs >= 2 ? (_jsxs("div", { className: "mt-0.5 font-mono text-[9px] text-neutral-500", children: ["outside ", event.outsideMs.toFixed(1)] })) : null, event.render !== null ? (_jsxs("div", { className: "mt-0.5 font-mono text-[9px] text-neutral-600", children: ["draws ", event.render.drawCalls, " \u00B7 tris ", event.render.triangles.toLocaleString()] })) : null] }, `${event.at}-${index}`))) }));
 }
 function PerfPanel({ ctx }) {
     const rateRef = useRef({ version: 0, at: 0, perSecond: 0 });
     const frame = devtools.frame.stats();
     const render = devtools.render.latest();
+    const longs = devtools.frame.longFrames();
     const now = performance.now();
     const rate = rateRef.current;
     if (rate.at === 0) {
@@ -117,7 +202,8 @@ function PerfPanel({ ctx }) {
         const perSecond = ((ctx.version() - rate.version) / (now - rate.at)) * 1000;
         rateRef.current = { version: ctx.version(), at: now, perSecond };
     }
-    return (_jsxs("div", { className: "space-y-2", children: [frame === null ? (_jsx("div", { className: "text-neutral-400", children: "Waiting for frames\u2026" })) : (_jsxs(_Fragment, { children: [_jsx(FrameBars, { frames: frame.recentFrameMs }), _jsx(StatRow, { name: "fps", value: frame.fps.toFixed(0), alert: frame.fps < 50 }), _jsx(StatRow, { name: "frame avg / p95 / max", value: `${ms(frame.avgFrameMs)} / ${ms(frame.p95FrameMs)} / ${ms(frame.maxFrameMs)}`, alert: frame.p95FrameMs > LONG_FRAME_MS }), _jsx(StatRow, { name: "sim avg / max", value: `${ms(frame.avgSimMs)} / ${ms(frame.maxSimMs)}`, alert: frame.avgSimMs > 8 }), _jsx(StatRow, { name: `long frames (of ${frame.samples})`, value: String(frame.longFrames), alert: frame.longFrames > 5 })] })), render !== null ? (_jsxs(_Fragment, { children: [_jsx(StatRow, { name: "draw calls", value: String(render.drawCalls), alert: render.drawCalls > 1000 }), _jsx(StatRow, { name: "triangles", value: render.triangles.toLocaleString() }), _jsx(StatRow, { name: "geometries / textures", value: `${render.geometries} / ${render.textures}` })] })) : null, _jsx(StatRow, { name: "state notifies /s", value: rateRef.current.perSecond.toFixed(0), alert: rateRef.current.perSecond > 90 }), Object.entries(devtools.probes.read()).map(([name, value]) => (_jsx(StatRow, { name: name, value: String(value) }, name)))] }));
+    const diagnosis = frame !== null ? diagnose(frame, longs) : null;
+    return (_jsxs("div", { className: "jg-devtools-scroll max-h-[28rem] space-y-3 overflow-auto", children: [frame === null ? (_jsx("div", { className: "text-neutral-400", children: "Waiting for frames\u2026" })) : (_jsxs(_Fragment, { children: [_jsx(FrameBars, { frames: frame.recentFrameMs }), _jsx(StatRow, { name: "fps", value: frame.fps.toFixed(0), alert: frame.fps < 50 }), _jsx(StatRow, { name: "frame avg / p95 / max", value: `${ms(frame.avgFrameMs)} / ${ms(frame.p95FrameMs)} / ${ms(frame.maxFrameMs)}`, alert: frame.p95FrameMs > LONG_FRAME_MS }), _jsx(StatRow, { name: "sim avg / max", value: `${ms(frame.avgSimMs)} / ${ms(frame.maxSimMs)}`, alert: frame.avgSimMs > 8 }), _jsx(StatRow, { name: "outside avg / max", value: `${ms(frame.avgOutsideMs)} / ${ms(frame.maxOutsideMs)}`, alert: frame.avgOutsideMs > 12 }), _jsx(StatRow, { name: `long frames (of ${frame.samples})`, value: String(frame.longFrames), alert: frame.longFrames > 5 }), diagnosis !== null ? (_jsxs("div", { className: "rounded border border-amber-500/40 bg-amber-500/10 px-2 py-1.5 text-[10px] leading-snug text-amber-100", children: [_jsx("span", { className: "font-semibold text-amber-300", children: "Why slow \u00B7 " }), diagnosis] })) : (_jsx("div", { className: "text-[10px] text-emerald-400/90", children: "Frame budget healthy \u2014 no dominant hitch pattern." })), _jsxs("div", { className: "space-y-1", children: [_jsx(SectionLabel, { children: "frame budget" }), _jsx(BudgetSplit, { simMs: frame.avgSimMs, outsideMs: frame.avgOutsideMs })] }), _jsxs("div", { className: "space-y-1", children: [_jsx(SectionLabel, { children: "sim phases (avg)" }), _jsx(PhaseBars, { phases: frame.phases, avgSimMs: frame.avgSimMs })] })] })), _jsxs("div", { className: "space-y-1", children: [_jsxs("div", { className: "flex items-center justify-between gap-2", children: [_jsx(SectionLabel, { children: "long frames" }), longs.length > 0 ? (_jsx("button", { type: "button", className: "rounded border border-neutral-700 px-1.5 py-0.5 text-[9px] text-neutral-400 hover:bg-neutral-800", onClick: () => devtools.frame.clearLongFrames(), children: "Clear" })) : null] }), _jsx(LongFrameList, { events: longs })] }), render !== null ? (_jsxs("div", { className: "space-y-1", children: [_jsx(SectionLabel, { children: "render sample" }), _jsx(StatRow, { name: "draw calls", value: String(render.drawCalls), alert: render.drawCalls > 1000 }), _jsx(StatRow, { name: "triangles", value: render.triangles.toLocaleString() }), _jsx(StatRow, { name: "geometries / textures", value: `${render.geometries} / ${render.textures}` })] })) : null, _jsxs("div", { className: "space-y-1", children: [_jsx(SectionLabel, { children: "probes" }), _jsx(StatRow, { name: "state notifies /s", value: rateRef.current.perSecond.toFixed(0), alert: rateRef.current.perSecond > 90 }), Object.entries(devtools.probes.read()).map(([name, value]) => (_jsx(StatRow, { name: name, value: String(value) }, name)))] }), _jsx("div", { className: "text-[9px] leading-snug text-neutral-600", children: "Game code: measure(\"physics\", () => \u2026) inside onTick. Agents: snapshot().longFrames + frame.phases" })] }));
 }
 function LogsPanel() {
     const entries = devtools.logs.list().slice(-60);
@@ -142,35 +228,181 @@ function KeysPanel({ input }) {
         return _jsx("div", { className: "text-neutral-400", children: "This game declares no keybinds." });
     return (_jsx("div", { className: "jg-devtools-scroll max-h-64 space-y-0.5 overflow-auto", children: rows.map((row, index) => (_jsxs("div", { className: "flex items-baseline justify-between gap-3", children: [_jsx("span", { className: "text-neutral-300", children: row.action }), _jsxs("span", { className: "font-mono text-neutral-100", children: [row.codes, row.mode !== "press" ? _jsx("span", { className: "ml-1 text-[9px] uppercase text-neutral-500", children: row.mode }) : null] })] }, index))) }));
 }
+const LAYER_LABELS = {
+    hitboxes: "Damage hitboxes",
+    bodies: "Physical bodies",
+    projectiles: "Projectile paths",
+    muzzles: "Muzzle / shot origins",
+    aimLaser: "Aim laser (authoritative)",
+};
+function ColPanel() {
+    const state = useSyncExternalStore(collisionDebug.subscribe, () => collisionDebug.getState(), () => collisionDebug.getState());
+    return (_jsxs("div", { className: "space-y-2", children: [_jsx("div", { className: "text-[10px] text-neutral-500", children: "F2 world collision debugger \u00B7 layers stay on when panel closes \u00B7 zero cost when all off" }), _jsxs("div", { className: "flex gap-1", children: [_jsx("button", { type: "button", className: "rounded border border-neutral-600 px-2 py-0.5 text-neutral-300 hover:bg-neutral-800", onClick: () => collisionDebug.setAllLayers(true), children: "All on" }), _jsx("button", { type: "button", className: "rounded border border-neutral-600 px-2 py-0.5 text-neutral-300 hover:bg-neutral-800", onClick: () => collisionDebug.setAllLayers(false), children: "All off" })] }), _jsx("div", { className: "space-y-1", children: COLLISION_DEBUG_LAYERS.map((layer) => (_jsxs("label", { className: "flex cursor-pointer items-center gap-2 text-neutral-200", children: [_jsx("input", { type: "checkbox", checked: state.layers[layer], onChange: (event) => collisionDebug.setLayer(layer, event.target.checked) }), _jsx("span", { children: LAYER_LABELS[layer] })] }, layer))) }), _jsx("div", { className: "border-t border-neutral-800 pt-1.5 font-mono text-[9px] text-neutral-500", children: "hitbox pink \u00B7 body cyan \u00B7 muzzle red \u00B7 laser lime \u00B7 X damage \u00B7 \u25CB solid \u00B7 \u00B7 miss" })] }));
+}
 function ControlInput({ control, onWrite }) {
     const value = control.read();
     const write = (next) => {
-        control.write(next);
-        onWrite();
+        if (control.write(next))
+            onWrite();
     };
-    if (control.kind === "slider") {
-        return (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("input", { type: "range", className: "h-1 w-28 accent-emerald-400", min: control.min, max: control.max, step: control.step, value: Number(value), onChange: (event) => write(Number(event.target.value)) }), _jsx("input", { type: "number", className: "w-16 rounded border border-neutral-600 bg-neutral-900 px-1 py-0.5 font-mono text-neutral-100", step: control.step, value: Number(value), onChange: (event) => {
+    if (control.kind === "slider" || control.kind === "angle") {
+        const unit = control.unit ?? "rad";
+        const displayUnit = control.displayUnit ?? (control.kind === "angle" ? "deg" : unit);
+        const displayValue = control.kind === "angle" && typeof value === "number"
+            ? convertAngle(value, unit, displayUnit)
+            : Number(value);
+        const displayMin = control.min !== undefined && control.kind === "angle"
+            ? convertAngle(control.min, unit, displayUnit)
+            : control.min;
+        const displayMax = control.max !== undefined && control.kind === "angle"
+            ? convertAngle(control.max, unit, displayUnit)
+            : control.max;
+        const displayStep = control.step !== undefined && control.kind === "angle" && unit !== displayUnit
+            ? convertAngle(control.step, unit, displayUnit)
+            : control.step;
+        return (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("input", { type: "range", className: "h-1 w-28 accent-emerald-400", min: displayMin, max: displayMax, step: displayStep, value: displayValue, onChange: (event) => {
                         const next = Number(event.target.value);
-                        if (!Number.isNaN(next))
-                            write(next);
-                    } })] }));
+                        write(control.kind === "angle" ? convertAngle(next, displayUnit, unit) : next);
+                    } }), _jsx("input", { type: "number", className: "w-16 rounded border border-neutral-600 bg-neutral-900 px-1 py-0.5 font-mono text-neutral-100", step: displayStep, value: Number(displayValue.toFixed(4)), onChange: (event) => {
+                        const next = Number(event.target.value);
+                        if (!Number.isNaN(next)) {
+                            write(control.kind === "angle" ? convertAngle(next, displayUnit, unit) : next);
+                        }
+                    } }), control.kind === "angle" ? (_jsx("span", { className: "text-[10px] text-neutral-500", children: displayUnit })) : null] }));
     }
     if (control.kind === "toggle") {
         return (_jsx("input", { type: "checkbox", className: "h-4 w-4 accent-emerald-400", checked: Boolean(value), onChange: (event) => write(event.target.checked) }));
     }
     if (control.kind === "color") {
-        return (_jsx("input", { type: "color", className: "h-6 w-10 cursor-pointer rounded border border-neutral-600 bg-transparent", value: String(value), onChange: (event) => write(event.target.value) }));
+        const parsed = parseColor(value);
+        const rgb = parsed?.rgb ?? "#000000";
+        const alpha = parsed?.alpha ?? 1;
+        const showAlpha = control.hasAlpha === true || parsed?.hasAlpha === true;
+        return (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("input", { type: "color", className: "h-6 w-10 cursor-pointer rounded border border-neutral-600 bg-transparent", value: rgb, onChange: (event) => {
+                        if (showAlpha) {
+                            const a = Math.round(alpha * 255)
+                                .toString(16)
+                                .padStart(2, "0");
+                            write(`${event.target.value}${a}`);
+                        }
+                        else {
+                            write(event.target.value);
+                        }
+                    } }), showAlpha ? (_jsx("input", { type: "range", className: "h-1 w-16 accent-emerald-400", min: 0, max: 1, step: 0.01, value: alpha, onChange: (event) => {
+                        const nextAlpha = Number(event.target.value);
+                        const a = Math.round(nextAlpha * 255)
+                            .toString(16)
+                            .padStart(2, "0");
+                        write(`${rgb}${a}`);
+                    } })) : null] }));
     }
-    if (control.kind === "select") {
+    if (control.kind === "select" || control.kind === "enum") {
+        const choices = control.choices ??
+            control.options?.map((option) => ({ value: option, label: String(option) })) ??
+            [];
         return (_jsx("select", { className: "rounded border border-neutral-600 bg-neutral-900 px-1 py-0.5 text-neutral-100", value: String(value), onChange: (event) => {
-                const match = control.options?.find((option) => String(option) === event.target.value);
-                write(match ?? event.target.value);
-            }, children: control.options?.map((option) => (_jsx("option", { value: String(option), children: String(option) }, String(option)))) }));
+                const match = choices.find((choice) => String(choice.value) === event.target.value);
+                if (match !== undefined)
+                    write(match.value);
+            }, children: choices.map((choice) => (_jsx("option", { value: String(choice.value), children: choice.label ?? String(choice.value) }, String(choice.value)))) }));
+    }
+    if (control.kind === "vec2" || control.kind === "vec3" || control.kind === "vec4") {
+        const axes = Array.isArray(value) ? value : [];
+        const labels = control.axisLabels ?? ["x", "y", "z", "w"];
+        return (_jsx("div", { className: "flex flex-wrap items-center gap-1", children: axes.map((axis, index) => (_jsxs("label", { className: "flex items-center gap-0.5 text-[10px] text-neutral-400", children: [_jsx("span", { children: labels[index] }), _jsx("input", { type: "number", className: "w-14 rounded border border-neutral-600 bg-neutral-900 px-1 py-0.5 font-mono text-neutral-100", min: control.axisMin?.[index], max: control.axisMax?.[index], step: control.axisStep?.[index] ?? control.step, value: axis, onChange: (event) => {
+                            const next = Number(event.target.value);
+                            if (Number.isNaN(next))
+                                return;
+                            const copy = axes.slice();
+                            copy[index] = next;
+                            write(copy);
+                        } })] }, labels[index] ?? index))) }));
+    }
+    if (control.kind === "interval") {
+        const interval = value !== null && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : { min: 0, max: 0 };
+        const writeInterval = (min, max) => write({ min, max });
+        return (_jsxs("div", { className: "flex items-center gap-1", children: [_jsx("input", { type: "number", className: "w-14 rounded border border-neutral-600 bg-neutral-900 px-1 py-0.5 font-mono text-neutral-100", min: control.min, max: control.max, step: control.step, value: interval.min, onChange: (event) => {
+                        const next = Number(event.target.value);
+                        if (!Number.isNaN(next))
+                            writeInterval(next, interval.max);
+                    } }), _jsx("span", { className: "text-neutral-500", children: "\u2026" }), _jsx("input", { type: "number", className: "w-14 rounded border border-neutral-600 bg-neutral-900 px-1 py-0.5 font-mono text-neutral-100", min: control.min, max: control.max, step: control.step, value: interval.max, onChange: (event) => {
+                        const next = Number(event.target.value);
+                        if (!Number.isNaN(next))
+                            writeInterval(interval.min, next);
+                    } })] }));
     }
     return (_jsx("input", { type: "text", className: "w-32 rounded border border-neutral-600 bg-neutral-900 px-1 py-0.5 font-mono text-neutral-100", value: String(value), onChange: (event) => write(event.target.value) }));
 }
 function formatPreview(value) {
-    return typeof value === "number" ? String(Math.round(value * 1000) / 1000) : String(value);
+    if (typeof value === "number")
+        return String(Math.round(value * 1000) / 1000);
+    if (Array.isArray(value))
+        return value.map((entry) => formatPreview(entry)).join(", ");
+    if (value !== null && typeof value === "object") {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return String(value);
+        }
+    }
+    return String(value);
+}
+const TUNABLE_ACRONYMS = new Set([
+    "fov",
+    "fps",
+    "ms",
+    "ui",
+    "ai",
+    "id",
+    "uv",
+    "rgb",
+    "rgba",
+    "hp",
+    "mp",
+    "xp",
+    "npc",
+    "pvp",
+    "pve",
+    "rts",
+    "hud",
+    "lod",
+    "gpu",
+    "cpu",
+]);
+function humanizeTunableSegment(segment) {
+    if (/^\d+$/.test(segment))
+        return `#${segment}`;
+    return segment
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .split(/\s+/)
+        .filter((part) => part.length > 0)
+        .map((part) => {
+        const lower = part.toLowerCase();
+        if (TUNABLE_ACRONYMS.has(lower))
+            return lower.toUpperCase();
+        return part.charAt(0).toUpperCase() + part.slice(1);
+    })
+        .join(" ");
+}
+function tunableGroupTitle(table, key) {
+    const dot = key.lastIndexOf(".");
+    if (dot < 0)
+        return humanizeTunableSegment(table);
+    const parent = key.slice(0, dot);
+    const parts = parent.split(".").map(humanizeTunableSegment);
+    return `${humanizeTunableSegment(table)} · ${parts.join(" · ")}`;
+}
+function tunableRowLabel(key) {
+    const leaf = key.includes(".") ? key.slice(key.lastIndexOf(".") + 1) : key;
+    return humanizeTunableSegment(leaf);
+}
+function tunableGroupKey(table, key) {
+    const dot = key.lastIndexOf(".");
+    return dot < 0 ? table : `${table}/${key.slice(0, dot)}`;
 }
 function deltaSnippet(discovered) {
     const overrides = devtools.overrides.export();
@@ -199,13 +431,17 @@ function deltaSnippet(discovered) {
 }
 function TunePanel({ gameName }) {
     const [deltasCopied, setDeltasCopied] = useState(false);
+    const [query, setQuery] = useState("");
     const controls = devtools.controls.list();
-    const discovered = devtools.discover.list();
+    const allDiscovered = devtools.discover.list();
     const persist = () => persistDevtoolsOverrides(gameName);
-    const discoveredIds = new Set(discovered.map((entry) => entry.id));
-    const explicit = controls.filter((control) => !discoveredIds.has(control.name));
+    const discoveredIds = new Set(allDiscovered.map((entry) => entry.id));
+    const needle = query.trim().toLowerCase();
+    const matches = (id) => needle === "" || id.toLowerCase().includes(needle);
+    const discovered = allDiscovered.filter((entry) => entry.enabled || matches(entry.id));
+    const explicit = controls.filter((control) => !discoveredIds.has(control.name) && matches(control.name));
     const controlByName = new Map(controls.map((control) => [control.name, control]));
-    const snippet = deltaSnippet(discovered);
+    const snippet = deltaSnippet(allDiscovered);
     const copyDeltas = () => {
         if (snippet === null)
             return;
@@ -219,19 +455,24 @@ function TunePanel({ gameName }) {
         setDeltasCopied(true);
         setTimeout(() => setDeltasCopied(false), 1500);
     };
-    if (explicit.length === 0 && discovered.length === 0) {
-        return (_jsxs("div", { className: "space-y-2 text-neutral-400", children: [_jsx("div", { children: "Nothing discovered." }), _jsxs("div", { className: "font-mono text-[10px] text-neutral-500", children: ["export const TUNING = { gravity: -22, skyColor: \"#87ceeb\" };", _jsx("br", {}), "Exported tables of numbers, booleans, and colors appear here", _jsx("br", {}), "automatically — check one to control it live."] })] }));
+    if (controls.length === 0 && allDiscovered.length === 0) {
+        return (_jsxs("div", { className: "space-y-2 text-neutral-400", children: [_jsx("div", { children: "Nothing discovered." }), _jsxs("div", { className: "font-mono text-[10px] text-neutral-500", children: ["export const TUNING = { gravity: -22, skyColor: \"#87ceeb\" };", _jsx("br", {}), "Nested numbers/booleans/colors auto-discover. Schema kinds:", _jsx("br", {}), "vec2/3/4 · interval · angle · enum · color+alpha via tunable() or scan meta."] })] }));
     }
-    const tables = new Map();
+    const groups = new Map();
     for (const entry of discovered) {
-        const list = tables.get(entry.table) ?? [];
-        list.push(entry);
-        tables.set(entry.table, list);
+        const groupKey = tunableGroupKey(entry.table, entry.key);
+        const existing = groups.get(groupKey);
+        if (existing !== undefined) {
+            existing.entries.push(entry);
+        }
+        else {
+            groups.set(groupKey, { title: tunableGroupTitle(entry.table, entry.key), entries: [entry] });
+        }
     }
     return (_jsxs("div", { className: "jg-devtools-scroll max-h-72 space-y-3 overflow-auto", children: [_jsxs("div", { className: "flex gap-1.5", children: [_jsx("button", { type: "button", className: "rounded border border-neutral-600 px-2 py-0.5 text-neutral-300 hover:bg-neutral-800", onClick: () => {
                             devtools.controls.resetAll();
                             persist();
-                        }, children: "Reset all" }), _jsx("button", { type: "button", disabled: snippet === null, className: "rounded border border-neutral-600 px-2 py-0.5 text-neutral-300 hover:bg-neutral-800 disabled:opacity-40 disabled:hover:bg-transparent", onClick: copyDeltas, title: "Copy changed values as source snippets to paste upstream", children: deltasCopied ? "Copied" : "Copy deltas" })] }), explicit.length > 0 ? (_jsxs("div", { className: "space-y-1.5", children: [_jsx("div", { className: "text-[9px] uppercase tracking-wide text-neutral-500", children: "registered" }), explicit.map((control) => (_jsxs("div", { className: "flex items-center justify-between gap-3", children: [_jsx("span", { className: "text-neutral-300", title: control.name, children: control.label }), _jsx(ControlInput, { control: control, onWrite: persist })] }, control.name)))] })) : null, [...tables.entries()].map(([table, entries]) => (_jsxs("div", { className: "space-y-1.5", children: [_jsx("div", { className: "text-[9px] uppercase tracking-wide text-neutral-500", children: table }), entries.map((entry) => {
+                        }, children: "Reset all" }), _jsx("button", { type: "button", disabled: snippet === null, className: "rounded border border-neutral-600 px-2 py-0.5 text-neutral-300 hover:bg-neutral-800 disabled:opacity-40 disabled:hover:bg-transparent", onClick: copyDeltas, title: "Copy changed values as source snippets to paste upstream", children: deltasCopied ? "Copied" : "Copy deltas" }), _jsx("input", { type: "text", value: query, onChange: (event) => setQuery(event.target.value), placeholder: "filter\u2026", className: "min-w-0 flex-1 rounded border border-neutral-600 bg-transparent px-2 py-0.5 text-neutral-200 placeholder:text-neutral-600 focus:outline-none" })] }), explicit.length === 0 && discovered.length === 0 ? (_jsxs("div", { className: "text-neutral-500", children: ["No tunables match \u201C", query, "\u201D."] })) : null, explicit.length > 0 ? (_jsxs("div", { className: "space-y-1.5", children: [_jsx("div", { className: "text-[9px] uppercase tracking-wide text-neutral-500", children: "registered" }), explicit.map((control) => (_jsxs("div", { className: "flex items-center justify-between gap-3", children: [_jsx("span", { className: "text-neutral-300", title: control.name, children: control.label.includes(".") ? tunableRowLabel(control.label) : control.label }), _jsx(ControlInput, { control: control, onWrite: persist })] }, control.name)))] })) : null, [...groups.entries()].map(([groupKey, group]) => (_jsxs("div", { className: "space-y-1.5", children: [_jsx("div", { className: "text-[9px] uppercase tracking-wide text-neutral-500", children: group.title }), group.entries.map((entry) => {
                         const control = entry.enabled ? controlByName.get(entry.id) : undefined;
                         return (_jsxs("div", { className: "flex items-center justify-between gap-3", children: [_jsxs("label", { className: "flex min-w-0 items-center gap-1.5 text-neutral-300", title: entry.id, children: [_jsx("input", { type: "checkbox", className: "h-3 w-3 shrink-0 accent-emerald-400", checked: entry.enabled, onChange: (event) => {
                                                 if (event.target.checked)
@@ -239,10 +480,103 @@ function TunePanel({ gameName }) {
                                                 else
                                                     devtools.discover.disable(entry.id);
                                                 persist();
-                                            } }), _jsx("span", { className: "truncate", children: entry.key })] }), control !== undefined ? (_jsx(ControlInput, { control: control, onWrite: persist })) : (_jsx("span", { className: "font-mono text-neutral-500", children: formatPreview(entry.read()) }))] }, entry.id));
-                    })] }, table)))] }));
+                                            } }), _jsx("span", { className: "truncate", children: tunableRowLabel(entry.key) })] }), control !== undefined ? (_jsx(ControlInput, { control: control, onWrite: persist })) : (_jsx("span", { className: "font-mono text-neutral-500", children: formatPreview(entry.read()) }))] }, entry.id));
+                    })] }, groupKey)))] }));
+}
+function roundMs(value, digits = 1) {
+    const scale = 10 ** digits;
+    return Math.round(value * scale) / scale;
 }
-function buildReport(playable) {
+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,
+    };
+}
+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,
+    };
+}
+export function buildFullReport(playable) {
     return { game: playable.game.name, ...devtools.snapshot() };
 }
 export function DevtoolsOverlay({ open, ctx, playable, multiplayer, }) {
@@ -253,11 +587,19 @@ export function DevtoolsOverlay({ open, ctx, playable, multiplayer, }) {
     useEffect(() => {
         devtools.logs.captureConsole();
         globalThis.__JG_DEVTOOLS = {
-            snapshot: () => buildReport(playable),
+            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)
@@ -298,7 +640,7 @@ export function DevtoolsOverlay({ open, ctx, playable, multiplayer, }) {
     if (!open)
         return null;
     const copyReport = () => {
-        const report = JSON.stringify(buildReport(playable), null, 2);
+        const report = JSON.stringify(buildLeanReport(playable), null, 2);
         const clipboard = navigator.clipboard;
         if (clipboard !== undefined) {
             void clipboard.writeText(report).catch(() => console.log(report));
@@ -309,7 +651,7 @@ export function DevtoolsOverlay({ open, ctx, playable, multiplayer, }) {
         setCopied(true);
         setTimeout(() => setCopied(false), 1500);
     };
-    return (_jsxs("div", { className: "pointer-events-auto absolute left-4 top-4 z-50 w-80 rounded border border-neutral-700 bg-neutral-950/95 p-3 text-xs text-neutral-100 shadow-2xl", children: [_jsx("style", { children: `
+    return (_jsxs("div", { className: "pointer-events-auto absolute left-4 top-4 z-50 w-[22rem] rounded border border-neutral-700 bg-neutral-950/95 p-3 text-xs text-neutral-100 shadow-2xl", children: [_jsx("style", { children: `
         .jg-devtools-scroll {
           scrollbar-width: thin;
           scrollbar-color: #52525b #18181b;
@@ -330,5 +672,5 @@ export function DevtoolsOverlay({ open, ctx, playable, multiplayer, }) {
         .jg-devtools-scroll::-webkit-scrollbar-thumb:hover {
           background-color: #71717a;
         }
-      ` }), _jsxs("div", { className: "mb-2 flex items-center justify-between", children: [_jsxs("span", { className: "font-semibold uppercase tracking-wide text-neutral-300", children: [playable.game.name, " devtools"] }), _jsx("button", { type: "button", className: "rounded border border-neutral-600 px-2 py-0.5 text-neutral-300 hover:bg-neutral-800", onClick: copyReport, children: copied ? "Copied" : "Copy report" })] }), _jsx("div", { className: "mb-2 flex gap-1", children: TABS.map((entry) => (_jsx("button", { type: "button", className: `rounded px-2 py-0.5 ${tab === entry.id ? "bg-neutral-100 text-neutral-950" : "text-neutral-400 hover:bg-neutral-800"}`, onClick: () => setTab(entry.id), children: entry.label }, entry.id))) }), tab === "perf" ? _jsx(PerfPanel, { ctx: ctx }) : null, tab === "logs" ? _jsx(LogsPanel, {}) : null, tab === "net" ? _jsx(NetPanel, { multiplayer: multiplayer }) : null, tab === "keys" ? _jsx(KeysPanel, { input: playable.game.input }) : null, tab === "tune" ? _jsx(TunePanel, { gameName: playable.game.name }) : null, _jsx("div", { className: "mt-2 border-t border-neutral-800 pt-1.5 text-[9px] text-neutral-500", children: "F2 toggles \u00B7 agents: window.__JG_DEVTOOLS.snapshot()" })] }));
+      ` }), _jsxs("div", { className: "mb-2 flex items-center justify-between", children: [_jsxs("span", { className: "font-semibold uppercase tracking-wide text-neutral-300", children: [playable.game.name, " devtools"] }), _jsx("button", { type: "button", className: "rounded border border-neutral-600 px-2 py-0.5 text-neutral-300 hover:bg-neutral-800", onClick: copyReport, children: copied ? "Copied" : "Copy report" })] }), _jsx("div", { className: "mb-2 flex gap-1", children: TABS.map((entry) => (_jsx("button", { type: "button", className: `rounded px-2 py-0.5 ${tab === entry.id ? "bg-neutral-100 text-neutral-950" : "text-neutral-400 hover:bg-neutral-800"}`, onClick: () => setTab(entry.id), children: entry.label }, entry.id))) }), tab === "perf" ? _jsx(PerfPanel, { ctx: ctx }) : null, tab === "logs" ? _jsx(LogsPanel, {}) : null, tab === "net" ? _jsx(NetPanel, { multiplayer: multiplayer }) : null, tab === "keys" ? _jsx(KeysPanel, { input: playable.game.input }) : null, tab === "tune" ? _jsx(TunePanel, { gameName: playable.game.name }) : null, tab === "col" ? _jsx(ColPanel, {}) : null, _jsx("div", { className: "mt-2 border-t border-neutral-800 pt-1.5 text-[9px] text-neutral-500", children: "F2 toggles \u00B7 Col = collision \u00B7 agents: __JG_DEVTOOLS.snapshot() \u00B7 .collisionDebug" })] }));
 }

package/dist/devtools/collisionDebug.d.ts

@@ -0,0 +1,57 @@
+import type { Aim } from "@jgengine/core/scene/spatial";
+import type { ShotOriginPolicy } from "@jgengine/core/combat/shotOrigin";
+import type { EntityPosition } from "@jgengine/core/scene/entityStore";
+export type CollisionDebugLayer = "hitboxes" | "bodies" | "projectiles" | "muzzles" | "aimLaser";
+export declare const COLLISION_DEBUG_LAYERS: readonly CollisionDebugLayer[];
+export type CollisionDebugLayers = Record<CollisionDebugLayer, boolean>;
+export interface AimProbeConfig {
+    from: string;
+    aim: Aim;
+    originPolicy?: ShotOriginPolicy;
+    maxDistance?: number;
+}
+export interface ProjectileDebugTrace {
+    id: number;
+    origin: EntityPosition;
+    at: EntityPosition;
+    hit: boolean;
+    bornMs: number;
+}
+export interface CollisionDebugState {
+    layers: CollisionDebugLayers;
+    aimProbe: AimProbeConfig | null;
+    projectileTraces: readonly ProjectileDebugTrace[];
+    /** Caps retained projectile paths/muzzle marks. */
+    maxProjectileTraces: number;
+    /** How long a projectile path stays visible (ms). */
+    projectileTraceLifeMs: number;
+}
+export type CollisionDebugListener = () => void;
+export declare function createDefaultCollisionDebugState(): CollisionDebugState;
+export declare function anyCollisionLayerOn(layers: CollisionDebugLayers): boolean;
+export declare function colliderScanNeeded(layers: CollisionDebugLayers): boolean;
+export declare function projectileListenNeeded(layers: CollisionDebugLayers): boolean;
+export declare function aimProbeNeeded(layers: CollisionDebugLayers): boolean;
+export interface CollisionDebugController {
+    getState(): CollisionDebugState;
+    subscribe(listener: CollisionDebugListener): () => void;
+    setLayer(layer: CollisionDebugLayer, on: boolean): void;
+    toggleLayer(layer: CollisionDebugLayer): void;
+    setLayers(partial: Partial<CollisionDebugLayers>): void;
+    setAllLayers(on: boolean): void;
+    /** Updates aim probe without notifying subscribers (per-frame safe). */
+    setAimProbe(probe: AimProbeConfig | null): void;
+    getAimProbe(): AimProbeConfig | null;
+    pushProjectileTrace(input: {
+        origin: EntityPosition;
+        at: EntityPosition;
+        hit: boolean;
+        nowMs?: number;
+    }): void;
+    pruneProjectileTraces(nowMs: number): void;
+    reset(): void;
+    /** True when any overlay work is scheduled. */
+    isActive(): boolean;
+}
+export declare function createCollisionDebugController(initial?: CollisionDebugState): CollisionDebugController;
+export declare const collisionDebug: CollisionDebugController;