@jgengine/shell 0.7.0 → 0.8.0

package/dist/camera/rigResolve.js

@@ -0,0 +1,52 @@
+/**
+ * Resolves which rig mounts from a `GameCameraConfig`. Precedence, most to least
+ * specific: an explicit `rig` field always wins; then `perspective: "first"`
+ * (the historical shorthand for `rig: "orbit" | "first"`); then the mere presence
+ * of a rig's own config block selects that rig, checked in the fixed order below
+ * (#207.8) so a config carrying more than one block resolves deterministically
+ * instead of depending on object key order. Set `rig` explicitly to break a tie.
+ */
+export function resolveRigKind(config) {
+    if (config?.rig !== undefined)
+        return config.rig;
+    if (config?.perspective === "first")
+        return "first";
+    if (config?.topDown !== undefined)
+        return "topDown";
+    if (config?.rts !== undefined)
+        return "rts";
+    if (config?.shoulder !== undefined)
+        return "shoulder";
+    if (config?.lockOn !== undefined)
+        return "lockOn";
+    if (config?.chase !== undefined)
+        return "chase";
+    if (config?.observer !== undefined)
+        return "observer";
+    if (config?.turntable !== undefined)
+        return "turntable";
+    if (config?.sideScroll !== undefined)
+        return "sideScroll";
+    if (config?.inspection !== undefined)
+        return "inspection";
+    return "orbit";
+}
+/**
+ * The turntable rig is a flat facade over the observer's point-orbit mode: map
+ * its `target`/`distance`/… onto an observer block so ObserverRig runs unchanged.
+ */
+export function turntableAsObserver(config) {
+    const t = config?.turntable;
+    if (t === undefined)
+        return config ?? {};
+    const observer = {
+        ...(t.target !== undefined ? { bind: { kind: "point", position: t.target } } : {}),
+        ...(t.distance !== undefined ? { distance: t.distance } : {}),
+        ...(t.height !== undefined ? { height: t.height } : {}),
+        ...(t.lookHeight !== undefined ? { lookHeight: t.lookHeight } : {}),
+        ...(t.orbitSpeed !== undefined ? { orbitSpeed: t.orbitSpeed } : {}),
+        ...(t.startAngle !== undefined ? { startAngle: t.startAngle } : {}),
+        ...(t.fov !== undefined ? { fov: t.fov } : {}),
+    };
+    return { ...config, observer };
+}

package/dist/defineGame.d.ts

@@ -0,0 +1,16 @@
+import type { ComponentType } from "react";
+import { type GameDefinitionConfig, type GameLoop } from "@jgengine/core/game/defineGame";
+import type { GameContext, GameContextContent } from "@jgengine/core/runtime/gameContext";
+import type { ModelAssetRef } from "@jgengine/core/scene/assetCatalog";
+import type { PlayableGame } from "./registry.js";
+type EngineFields<TAssetRef extends ModelAssetRef> = Omit<GameDefinitionConfig<TAssetRef>, "loop" | "ui" | "multiplayer"> & {
+    multiplayer?: GameDefinitionConfig<TAssetRef>["multiplayer"];
+};
+type PresentationFields = Omit<PlayableGame, "game" | "content" | "loop" | "GameUI"> & {
+    content?: GameContextContent;
+    loop?: Partial<GameLoop<GameContext>>;
+    GameUI?: ComponentType;
+};
+export type GameConfig<TAssetRef extends ModelAssetRef = ModelAssetRef> = EngineFields<TAssetRef> & PresentationFields;
+export declare function defineGame<TAssetRef extends ModelAssetRef = ModelAssetRef>(config: GameConfig<TAssetRef>): PlayableGame;
+export {};

package/dist/defineGame.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { defineGame as defineEngineGame, } from "@jgengine/core/game/defineGame";
+import { offline } from "@jgengine/core/runtime/adapter";
+import { EnvironmentScene } from "./environment.js";
+const noop = () => { };
+function worldBackdrop(feature) {
+    return function WorldBackdrop() {
+        return _jsx(EnvironmentScene, { feature: feature });
+    };
+}
+const emptyUi = () => null;
+export function defineGame(config) {
+    const { content, loop, GameUI, environment, camera, multiplayer, WorldOverlay, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, worldHealthBars, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting, backdrop, shadows, presentation, objectStyles, devtools, ...engineFields } = config;
+    const game = defineEngineGame({ ...engineFields, multiplayer: multiplayer ?? offline() });
+    return {
+        game,
+        content: content ?? {},
+        loop: {
+            onInit: loop?.onInit ?? noop,
+            onNewPlayer: loop?.onNewPlayer ?? noop,
+            onTick: loop?.onTick ?? noop,
+        },
+        GameUI: GameUI ?? emptyUi,
+        environment: environment ??
+            (game.world?.kind === "environment" ? worldBackdrop(game.world) : undefined),
+        camera: camera ?? { perspective: "third" },
+        WorldOverlay,
+        renderEntity,
+        renderObject,
+        entitySprites,
+        entityModels,
+        objectModels,
+        hotbarSelection,
+        prompts,
+        pointer,
+        touch,
+        worldHealthBars,
+        audio,
+        entitySounds,
+        objectSounds,
+        worldItem,
+        collision,
+        movement,
+        lighting,
+        backdrop,
+        shadows,
+        presentation,
+        objectStyles,
+        devtools,
+    };
+}

package/dist/devtools/DevtoolsOverlay.d.ts

@@ -0,0 +1,14 @@
+import { type DevtoolsOverrides } 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 declare function persistDevtoolsOverrides(gameName: string): DevtoolsOverrides;
+export declare function applyStoredDevtoolsOverrides(gameName: string): void;
+export declare function withDevtoolsLatency(multiplayer: ShellMultiplayer): ShellMultiplayer;
+export declare function DevtoolsRendererProbe(): null;
+export declare function DevtoolsOverlay({ open, ctx, playable, multiplayer, }: {
+    open: boolean;
+    ctx: GameContext;
+    playable: PlayableGame;
+    multiplayer: ShellMultiplayer | null;
+}): import("react").JSX.Element | null;

package/dist/devtools/DevtoolsOverlay.js

@@ -0,0 +1,334 @@
+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 { bindingLabel } from "@jgengine/core/input/actionBindings";
+const REFRESH_MS = 250;
+const LONG_FRAME_MS = 33.4;
+function overridesStorageKey(gameName) {
+    return `jg-devtools:${gameName}`;
+}
+function readStoredOverrides(gameName) {
+    try {
+        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;
+    }
+    catch {
+        return null;
+    }
+}
+export function persistDevtoolsOverrides(gameName) {
+    const overrides = devtools.overrides.export();
+    try {
+        localStorage.setItem(overridesStorageKey(gameName), JSON.stringify(overrides));
+    }
+    catch {
+        return overrides;
+    }
+    return overrides;
+}
+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)
+        return;
+    devtools.overrides.apply(stored);
+    console.info(`[jgengine:devtools] applied ${applied} stored override(s) for ${gameName}`);
+}
+export function withDevtoolsLatency(multiplayer) {
+    return {
+        ...multiplayer,
+        backend: {
+            ...instrumentLatency(multiplayer.backend, ["pushFeedEntry"]),
+            transport: instrumentLatency(multiplayer.backend.transport, ["joinServer", "leaveServer", "runCommand"]),
+        },
+    };
+}
+export function DevtoolsRendererProbe() {
+    const frameCounter = useRef(0);
+    useFrame((state) => {
+        frameCounter.current += 1;
+        if (frameCounter.current % 30 !== 0)
+            return;
+        const info = state.gl.info;
+        devtools.render.record({
+            drawCalls: info.render.calls,
+            triangles: info.render.triangles,
+            geometries: info.memory.geometries,
+            textures: info.memory.textures,
+        });
+    });
+    return null;
+}
+function keybindRows(input) {
+    const rows = [];
+    for (const [action, codes] of Object.entries(input ?? {})) {
+        const entries = flattenCodes(codes);
+        for (const entry of entries)
+            rows.push({ action, ...entry });
+    }
+    return rows;
+}
+function flattenCodes(codes) {
+    if (Array.isArray(codes)) {
+        return [{ codes: codes.map(bindingLabel).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" });
+    }
+    if (modes.toggle !== undefined && modes.toggle.length > 0) {
+        result.push({ codes: modes.toggle.map(bindingLabel).join(" / "), mode: "toggle" });
+    }
+    return result;
+}
+const TABS = [
+    { id: "perf", label: "Perf" },
+    { id: "tune", label: "Tune" },
+    { id: "logs", label: "Logs" },
+    { id: "net", label: "Net" },
+    { id: "keys", label: "Keys" },
+];
+function ms(value) {
+    return `${value.toFixed(1)}ms`;
+}
+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))) }));
+}
+function PerfPanel({ ctx }) {
+    const rateRef = useRef({ version: 0, at: 0, perSecond: 0 });
+    const frame = devtools.frame.stats();
+    const render = devtools.render.latest();
+    const now = performance.now();
+    const rate = rateRef.current;
+    if (rate.at === 0) {
+        rateRef.current = { version: ctx.version(), at: now, perSecond: 0 };
+    }
+    else if (now - rate.at >= 900) {
+        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)))] }));
+}
+function LogsPanel() {
+    const entries = devtools.logs.list().slice(-60);
+    const colors = {
+        error: "text-red-400",
+        warn: "text-amber-300",
+        info: "text-sky-300",
+        log: "text-neutral-300",
+    };
+    return (_jsxs("div", { className: "space-y-2", 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.logs.clear(), children: "Clear" }), _jsxs("div", { className: "jg-devtools-scroll max-h-64 space-y-0.5 overflow-auto font-mono text-[10px]", children: [entries.length === 0 ? _jsx("div", { className: "text-neutral-400", children: "No logs captured yet." }) : null, entries.map((entry, index) => (_jsxs("div", { className: colors[entry.level], children: [_jsxs("span", { className: "text-neutral-500", children: [new Date(entry.at).toLocaleTimeString(), " "] }), entry.message] }, index)))] })] }));
+}
+function NetPanel({ multiplayer }) {
+    const stats = devtools.latency.stats();
+    if (multiplayer === null) {
+        return _jsx("div", { className: "text-neutral-400", children: "Offline \u2014 no multiplayer backend attached." });
+    }
+    return (_jsxs("div", { className: "space-y-2", children: [_jsx(StatRow, { name: "game / user", value: `${multiplayer.gameId} / ${multiplayer.userId}` }), stats === null ? (_jsx("div", { className: "text-neutral-400", children: "No round trips observed yet \u2014 latency is sampled from real backend calls." })) : (_jsxs(_Fragment, { children: [_jsx(StatRow, { name: "last round trip", value: ms(stats.lastMs), alert: stats.lastMs > 250 }), _jsx(StatRow, { name: "avg / min / max", value: `${ms(stats.avgMs)} / ${ms(stats.minMs)} / ${ms(stats.maxMs)}` }), _jsx(StatRow, { name: "samples", value: String(stats.samples) })] }))] }));
+}
+function KeysPanel({ input }) {
+    const rows = keybindRows(input);
+    if (rows.length === 0)
+        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))) }));
+}
+function ControlInput({ control, onWrite }) {
+    const value = control.read();
+    const write = (next) => {
+        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) => {
+                        const next = Number(event.target.value);
+                        if (!Number.isNaN(next))
+                            write(next);
+                    } })] }));
+    }
+    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) }));
+    }
+    if (control.kind === "select") {
+        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)))) }));
+    }
+    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);
+}
+function deltaSnippet(discovered) {
+    const overrides = devtools.overrides.export();
+    if (Object.keys(overrides.values).length === 0)
+        return null;
+    const discoveredById = new Map(discovered.map((entry) => [entry.id, entry]));
+    const tables = new Map();
+    const flat = {};
+    for (const [name, value] of Object.entries(overrides.values)) {
+        const entry = discoveredById.get(name);
+        if (entry !== undefined) {
+            const values = tables.get(entry.table) ?? {};
+            values[entry.key] = value;
+            tables.set(entry.table, values);
+        }
+        else {
+            flat[name] = value;
+        }
+    }
+    const parts = [];
+    for (const [table, values] of tables)
+        parts.push(`${table}: ${JSON.stringify(values, null, 2)}`);
+    if (Object.keys(flat).length > 0)
+        parts.push(`controls: ${JSON.stringify(flat, null, 2)}`);
+    return parts.join("\n\n");
+}
+function TunePanel({ gameName }) {
+    const [deltasCopied, setDeltasCopied] = useState(false);
+    const controls = devtools.controls.list();
+    const discovered = 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 controlByName = new Map(controls.map((control) => [control.name, control]));
+    const snippet = deltaSnippet(discovered);
+    const copyDeltas = () => {
+        if (snippet === null)
+            return;
+        const clipboard = navigator.clipboard;
+        if (clipboard !== undefined) {
+            void clipboard.writeText(snippet).catch(() => console.log(snippet));
+        }
+        else {
+            console.log(snippet);
+        }
+        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."] })] }));
+    }
+    const tables = new Map();
+    for (const entry of discovered) {
+        const list = tables.get(entry.table) ?? [];
+        list.push(entry);
+        tables.set(entry.table, list);
+    }
+    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) => {
+                        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)
+                                                    devtools.discover.enable(entry.id);
+                                                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)))] }));
+}
+function buildReport(playable) {
+    return { game: playable.game.name, ...devtools.snapshot() };
+}
+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: () => buildReport(playable),
+            controls: devtools.controls,
+            discover: devtools.discover,
+        };
+    }, [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),
+        ];
+        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]);
+    if (!open)
+        return null;
+    const copyReport = () => {
+        const report = JSON.stringify(buildReport(playable), null, 2);
+        const clipboard = navigator.clipboard;
+        if (clipboard !== undefined) {
+            void clipboard.writeText(report).catch(() => console.log(report));
+        }
+        else {
+            console.log(report);
+        }
+        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: `
+        .jg-devtools-scroll {
+          scrollbar-width: thin;
+          scrollbar-color: #52525b #18181b;
+        }
+        .jg-devtools-scroll::-webkit-scrollbar {
+          width: 8px;
+          height: 8px;
+        }
+        .jg-devtools-scroll::-webkit-scrollbar-track {
+          background: #18181b;
+          border-radius: 9999px;
+        }
+        .jg-devtools-scroll::-webkit-scrollbar-thumb {
+          background-color: #52525b;
+          border-radius: 9999px;
+          border: 2px solid #18181b;
+        }
+        .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()" })] }));
+}

package/dist/environment/Daylight.d.ts

@@ -0,0 +1,50 @@
+import { type MutableRefObject } from "react";
+import * as THREE from "three";
+import type { SkyEnvironmentDescriptor } from "@jgengine/core/world/features";
+export interface SkyDomeProps {
+    topColor?: string;
+    horizonColor?: string;
+    radius?: number;
+    offset?: number;
+    exponent?: number;
+    /** Exposes the created shader material so a time-of-day driver can mutate its uniforms per frame without recreating it. */
+    materialRef?: MutableRefObject<THREE.ShaderMaterial | null>;
+}
+export declare function SkyDome({ topColor, horizonColor, radius, offset, exponent, materialRef, }?: SkyDomeProps): import("react").JSX.Element;
+export interface DaylightProps {
+    sky?: SkyDomeProps | false;
+    fog?: {
+        color?: string;
+        near?: number;
+        far?: number;
+    } | false;
+    sun?: {
+        position?: readonly [number, number, number];
+        intensity?: number;
+        color?: string;
+    };
+    ambient?: {
+        skyColor?: string;
+        groundColor?: string;
+        intensity?: number;
+    };
+}
+export declare function Daylight({ sky, fog, sun, ambient }?: DaylightProps): import("react").JSX.Element;
+/** Renders a fixed sky/sun/fog look sampled from `sky`'s preset (or, when `timeOfDay` is on but no clock drives it, its noon look). No per-frame updates. */
+export declare function SkyDaylight({ sky }: {
+    sky: SkyEnvironmentDescriptor;
+}): import("react").JSX.Element;
+export interface TimeOfDayDaylightProps {
+    sky: SkyEnvironmentDescriptor;
+    /** The world's `SimClock` (or a stub exposing `calendar().dayFraction`). Absent means static rendering. */
+    clock?: {
+        calendar(): {
+            dayFraction: number;
+        };
+    };
+}
+/**
+ * Drives `Daylight`'s sun/sky/fog from the world clock when `sky.timeOfDay` and `clock` are both present,
+ * sampling `daylightStateAt` every frame; otherwise renders the static preset look via `SkyDaylight`.
+ */
+export declare function TimeOfDayDaylight({ sky, clock }: TimeOfDayDaylightProps): import("react").JSX.Element;

package/dist/environment/Daylight.js

@@ -0,0 +1,100 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+import { daylightStateAt, SKY_PRESET_DAY_FRACTION } from "./daylightCycle.js";
+const SKY_TOP = "#3fa4f2";
+const SKY_HORIZON = "#e3f4ff";
+const FOG_COLOR = "#e9f6ff";
+const SUN_COLOR = "#fff1c9";
+const HEMI_SKY = "#bfe3ff";
+const HEMI_GROUND = "#4c6b34";
+export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius = 260, offset = 24, exponent = 0.65, materialRef, } = {}) {
+    const material = useMemo(() => {
+        return new THREE.ShaderMaterial({
+            uniforms: {
+                topColor: { value: new THREE.Color(topColor) },
+                bottomColor: { value: new THREE.Color(horizonColor) },
+                offset: { value: offset },
+                exponent: { value: exponent },
+            },
+            vertexShader: `
+        varying vec3 vWorldPosition;
+        void main() {
+          vec4 worldPosition = modelMatrix * vec4(position, 1.0);
+          vWorldPosition = worldPosition.xyz;
+          gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+        }
+      `,
+            fragmentShader: `
+        uniform vec3 topColor;
+        uniform vec3 bottomColor;
+        uniform float offset;
+        uniform float exponent;
+        varying vec3 vWorldPosition;
+        void main() {
+          float h = normalize(vWorldPosition + vec3(0.0, offset, 0.0)).y;
+          gl_FragColor = vec4(mix(bottomColor, topColor, max(pow(max(h, 0.0), exponent), 0.0)), 1.0);
+        }
+      `,
+            side: THREE.BackSide,
+            depthWrite: false,
+            fog: false,
+        });
+    }, [topColor, horizonColor, offset, exponent]);
+    useEffect(() => {
+        if (materialRef !== undefined)
+            materialRef.current = material;
+        return () => {
+            material.dispose();
+            if (materialRef !== undefined)
+                materialRef.current = null;
+        };
+    }, [material, materialRef]);
+    return (_jsx("mesh", { material: material, renderOrder: -1, children: _jsx("sphereGeometry", { args: [radius, 32, 16] }) }));
+}
+export function Daylight({ sky, fog, sun, ambient } = {}) {
+    const sunPosition = sun?.position ?? [120, 160, 70];
+    return (_jsxs(_Fragment, { children: [sky === false ? null : _jsx(SkyDome, { ...(sky ?? {}) }), fog === false ? null : (_jsx("fog", { attach: "fog", args: [fog?.color ?? FOG_COLOR, fog?.near ?? 70, fog?.far ?? 260] })), _jsx("hemisphereLight", { args: [ambient?.skyColor ?? HEMI_SKY, ambient?.groundColor ?? HEMI_GROUND, ambient?.intensity ?? 0.55] }), _jsx("directionalLight", { position: [sunPosition[0], sunPosition[1], sunPosition[2]], intensity: sun?.intensity ?? 0.85, color: sun?.color ?? SUN_COLOR, castShadow: true })] }));
+}
+/** Renders a fixed sky/sun/fog look sampled from `sky`'s preset (or, when `timeOfDay` is on but no clock drives it, its noon look). No per-frame updates. */
+export function SkyDaylight({ sky }) {
+    const state = useMemo(() => daylightStateAt(SKY_PRESET_DAY_FRACTION[sky.preset], sky), [sky]);
+    return (_jsx(Daylight, { sky: { topColor: state.skyTop, horizonColor: state.skyBottom }, fog: { color: sky.fog?.color ?? state.background, near: sky.fog?.near, far: sky.fog?.far }, sun: { position: state.sunPosition, intensity: state.sunIntensity }, ambient: { intensity: state.ambientIntensity } }));
+}
+/**
+ * Drives `Daylight`'s sun/sky/fog from the world clock when `sky.timeOfDay` and `clock` are both present,
+ * sampling `daylightStateAt` every frame; otherwise renders the static preset look via `SkyDaylight`.
+ */
+export function TimeOfDayDaylight({ sky, clock }) {
+    if (!sky.timeOfDay || clock === undefined)
+        return _jsx(SkyDaylight, { sky: sky });
+    return _jsx(DrivenDaylight, { sky: sky, clock: clock });
+}
+function DrivenDaylight({ sky, clock, }) {
+    const initial = useMemo(() => daylightStateAt(clock.calendar().dayFraction, sky), [clock, sky]);
+    const sunRef = useRef(null);
+    const hemiRef = useRef(null);
+    const fogRef = useRef(null);
+    const skyMaterialRef = useRef(null);
+    useFrame(() => {
+        const state = daylightStateAt(clock.calendar().dayFraction, sky);
+        const sun = sunRef.current;
+        if (sun !== null) {
+            sun.position.set(state.sunPosition[0], state.sunPosition[1], state.sunPosition[2]);
+            sun.intensity = state.sunIntensity;
+        }
+        const hemi = hemiRef.current;
+        if (hemi !== null)
+            hemi.intensity = state.ambientIntensity;
+        const fog = fogRef.current;
+        if (fog !== null)
+            fog.color.set(sky.fog?.color ?? state.background);
+        const skyMaterial = skyMaterialRef.current;
+        if (skyMaterial !== null) {
+            skyMaterial.uniforms.topColor.value.set(state.skyTop);
+            skyMaterial.uniforms.bottomColor.value.set(state.skyBottom);
+        }
+    });
+    return (_jsxs(_Fragment, { children: [_jsx(SkyDome, { topColor: initial.skyTop, horizonColor: initial.skyBottom, materialRef: skyMaterialRef }), _jsx("fog", { attach: "fog", ref: fogRef, args: [sky.fog?.color ?? initial.background, sky.fog?.near ?? 70, sky.fog?.far ?? 260] }), _jsx("hemisphereLight", { ref: hemiRef, args: [HEMI_SKY, HEMI_GROUND, initial.ambientIntensity] }), _jsx("directionalLight", { ref: sunRef, position: initial.sunPosition, intensity: initial.sunIntensity, color: SUN_COLOR, castShadow: true })] }));
+}