@jgengine/shell 0.24.0 → 0.26.0

package/dist/devtools/frameSampler.js

@@ -0,0 +1,345 @@
+import { devtools } from "@jgengine/core/devtools/devtools";
+import { roundReport, toReportLogs } from "@jgengine/core/devtools/report";
+import { REPORT_ENDPOINT_PATH } from "@jgengine/core/devtools/reportEndpoint";
+import { readUrlParam } from "@jgengine/core/devtools/urlFlags";
+/**
+ * In-page frame telemetry: the game reports on itself instead of needing a second
+ * process to attach a profiler. Frame timings come from the devtools frame ring,
+ * renderer counts from the live renderer, GPU-object creation from wrapped GL calls,
+ * and per-system numbers from `devtools.probes` — all read on demand, so nothing
+ * here runs on the hot path.
+ */
+/** Query flag that turns the sampler off for an A/B frame-time comparison. */
+export const TELEMETRY_FLAG = "telemetry";
+/** How long after the sampler starts the GL counters get their post-warmup baseline. */
+export const TELEMETRY_WARMUP_MS = 5_000;
+/** Cadence of the push to the dev server, in milliseconds. */
+export const REPORT_PUSH_MS = 1_000;
+const WATCHED_GL_CALLS = [
+    ["linkProgram", "programsLinked"],
+    ["createFramebuffer", "framebuffers"],
+    ["createBuffer", "buffers"],
+    ["createTexture", "textures"],
+    ["createVertexArray", "vertexArrays"],
+];
+function emptyGlTotals() {
+    return { programsLinked: 0, framebuffers: 0, buffers: 0, textures: 0, vertexArrays: 0 };
+}
+/**
+ * Wrap the live context's creation calls so a leak shows up as a non-zero counter.
+ * Only object creation is wrapped — never a draw call — so a steady-state frame
+ * pays nothing. Returns whether any call was actually wrapped, since a zero is only
+ * evidence when it was.
+ * @internal
+ */
+export function attachGlCounters(context) {
+    const totals = emptyGlTotals();
+    const target = context;
+    let attached = false;
+    for (const [method, key] of WATCHED_GL_CALLS) {
+        const original = target[method];
+        if (typeof original !== "function")
+            continue;
+        attached = true;
+        target[method] = (...args) => {
+            totals[key] += 1;
+            return original.apply(context, args);
+        };
+    }
+    return { totals, attached };
+}
+/**
+ * Count live three.js nodes from the scene the game is drawing; `null` when it cannot be walked.
+ * @internal
+ */
+export function countSceneNodes(scene) {
+    const candidate = scene;
+    if (candidate === null || candidate === undefined || typeof candidate.traverse !== "function") {
+        return { nodes: null, scenes: 0 };
+    }
+    try {
+        let nodes = 0;
+        candidate.traverse(() => {
+            nodes += 1;
+        });
+        return { nodes, scenes: 1 };
+    }
+    catch {
+        return { nodes: null, scenes: 0 };
+    }
+}
+function glReport(inputs) {
+    const since = inputs.since;
+    return {
+        programsLinked: since.programsLinked,
+        framebuffers: since.framebuffers,
+        buffers: since.buffers,
+        textures: since.textures,
+        vertexArrays: since.vertexArrays,
+        allocations: since.programsLinked + since.framebuffers + since.buffers + since.textures + since.vertexArrays,
+        residentPrograms: inputs.residentPrograms,
+        total: { ...inputs.totals },
+        attached: inputs.attached,
+    };
+}
+/**
+ * Assemble the shared report shape from live sources. Pure: every number arrives as
+ * an argument, so a test can assert the shape without a renderer or a browser.
+ * @internal
+ */
+export function buildFrameReport(inputs) {
+    const frame = inputs.frame;
+    const scaled = frame === null
+        ? { fps: 0, avgMs: 0, p95Ms: 0, maxMs: 0, samples: 0, longFrames: 0 }
+        : {
+            fps: roundReport(frame.fps, 1),
+            avgMs: roundReport(frame.avgFrameMs),
+            p95Ms: roundReport(frame.p95FrameMs),
+            maxMs: roundReport(frame.maxFrameMs),
+            samples: frame.samples,
+            longFrames: frame.longFrames,
+        };
+    const seconds = scaled.fps > 0 ? roundReport(scaled.samples / scaled.fps, 1) : 0;
+    return {
+        game: inputs.game,
+        gpu: inputs.gpu,
+        quality: inputs.quality,
+        viewport: inputs.viewport,
+        seconds,
+        at: inputs.at,
+        frame: scaled,
+        render: {
+            draws: inputs.render?.drawCalls ?? null,
+            triangles: inputs.render?.triangles ?? null,
+            geometries: inputs.render?.geometries ?? null,
+            textures: inputs.render?.textures ?? null,
+            nodes: inputs.scene.nodes,
+            nodesSource: inputs.scene.nodes === null ? "unavailable" : "scene-graph",
+            scenes: inputs.scene.scenes,
+        },
+        gl: glReport(inputs.gl),
+        sim: frame === null ? null : { avgMs: roundReport(frame.avgSimMs), outsideMs: roundReport(frame.avgOutsideMs) },
+        profile: null,
+        systems: inputs.systems,
+        logs: inputs.logs,
+        telemetry: {
+            source: "in-page",
+            warmedUp: inputs.warmedUp,
+            ageMs: Math.round(inputs.ageMs),
+            buildMs: roundReport(inputs.buildMs),
+            heapBytes: inputs.heapBytes,
+        },
+    };
+}
+function browserNow() {
+    const perf = globalThis.performance;
+    return perf !== undefined ? perf.now() : Date.now();
+}
+/**
+ * `Harbor Heat` -> `harbor-heat`, unless the dev runner's `?game=` says otherwise. The
+ * report is keyed by this, so it matches `bun run perf` and the budget file.
+ * @internal
+ */
+export function reportGameId(displayName) {
+    const fromRunner = readUrlParam("game");
+    if (fromRunner !== null && fromRunner.length > 0)
+        return fromRunner;
+    return displayName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+/**
+ * Ask the dev server whether its report route exists. This is the sampler's only
+ * production guard and it is behaviour, not a build flag: the route is mounted by the
+ * dev Vite configs only, so a shipped game answers this one request and installs
+ * nothing — no timers, no GL wrapping, no `window.__JG`. The website dev server serves
+ * the /play runner as a production build, which is why a build-time `PROD` check would
+ * wrongly disable the report there.
+ * @internal
+ */
+export async function probeReportRoute(endpoint = REPORT_ENDPOINT_PATH, game = "", fetchImpl = typeof fetch === "function" ? fetch : null, timeoutMs = 1_500) {
+    if (fetchImpl === null)
+        return false;
+    try {
+        const response = await fetchImpl(`${endpoint}?game=${encodeURIComponent(game)}`, {
+            signal: AbortSignal.timeout(timeoutMs),
+            cache: "no-store",
+        });
+        const type = response.headers.get("content-type") ?? "";
+        if (!type.includes("application/json"))
+            return false;
+        const body = (await response.json());
+        return typeof body?.error === "string" || body?.frame !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+function heapUsedBytes() {
+    const memory = globalThis.performance?.memory;
+    return typeof memory?.usedJSHeapSize === "number" ? memory.usedJSHeapSize : null;
+}
+function subtract(totals, baseline) {
+    const since = emptyGlTotals();
+    for (const key of Object.keys(since)) {
+        since[key] = Math.max(0, totals[key] - (baseline?.[key] ?? 0));
+    }
+    return since;
+}
+let installed = null;
+/**
+ * Reset the sampler's warmup baseline, so a fresh measurement starts from zero.
+ * @internal
+ */
+export function resetFrameTelemetry() {
+    installed?.resetWindow();
+}
+/**
+ * Install the sampler for the page: publishes `window.__JG.report()` and pushes the
+ * same record to the dev server's report route every second. Returns `null` when
+ * `?telemetry=off` asks for the comparison run; callers gate installation on
+ * {@link probeReportRoute}, so a shipped game never starts the sampler.
+ * @internal
+ */
+export function installFrameTelemetry(sources) {
+    if ((readUrlParam(TELEMETRY_FLAG) ?? "").toLowerCase() === "off")
+        return null;
+    if (typeof window === "undefined")
+        return null;
+    const startedAt = browserNow();
+    let baseline = null;
+    let disposed = false;
+    let pushFailures = 0;
+    let scheduled = null;
+    const gameId = reportGameId(sources.game);
+    const endpoint = sources.endpoint ?? REPORT_ENDPOINT_PATH;
+    const shouldPush = sources.push !== false && typeof fetch === "function";
+    const markWarmup = () => {
+        const ageMs = browserNow() - startedAt;
+        if (baseline === null && ageMs >= TELEMETRY_WARMUP_MS)
+            baseline = { ...sources.gl().totals };
+        return baseline !== null;
+    };
+    const buildReport = () => {
+        const started = browserNow();
+        const warmedUp = markWarmup();
+        const gl = sources.gl();
+        const report = buildFrameReport({
+            game: gameId,
+            gpu: sources.gpu(),
+            quality: sources.quality(),
+            viewport: sources.viewport(),
+            at: Date.now(),
+            frame: devtools.frame.stats(),
+            render: sources.render(),
+            scene: countSceneNodes(sources.scene()),
+            gl: {
+                totals: gl.totals,
+                since: subtract(gl.totals, baseline),
+                residentPrograms: sources.residentPrograms(),
+                attached: gl.attached,
+            },
+            systems: devtools.probes.systems(),
+            logs: toReportLogs(devtools.logs.snapshot()),
+            heapBytes: sources.heapBytes?.() ?? heapUsedBytes(),
+            ageMs: browserNow() - startedAt,
+            warmedUp,
+            buildMs: browserNow() - started,
+        });
+        return report;
+    };
+    const telemetry = {
+        report: buildReport,
+        resetWindow() {
+            baseline = null;
+            devtools.frame.reset();
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            clearInterval(timer);
+            if (scheduled !== null)
+                cancelIdle(scheduled);
+            window.removeEventListener("error", onError);
+            window.removeEventListener("unhandledrejection", onRejection);
+            document.removeEventListener("webglcontextlost", onContextLost, true);
+            const host = window;
+            if (host.__JG?.report === buildReport)
+                delete host.__JG;
+            if (installed === telemetry)
+                installed = null;
+        },
+    };
+    const pushOnce = async () => {
+        if (disposed)
+            return;
+        try {
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ gameId, report: buildReport() }),
+            });
+            if (!response.ok)
+                throw new Error(`report route answered ${response.status}`);
+            pushFailures = 0;
+        }
+        catch {
+            pushFailures += 1;
+            if (pushFailures === 3) {
+                // A missing route (production build, or a host without the dev plugin) is not worth retrying forever.
+                clearInterval(timer);
+            }
+        }
+    };
+    // Reports ride an idle callback so a build and its POST never land in a busy frame.
+    const run = () => {
+        scheduled = null;
+        void pushOnce();
+    };
+    const schedulePush = () => {
+        if (scheduled !== null || disposed)
+            return;
+        scheduled = scheduleIdle(run);
+    };
+    const timer = setInterval(schedulePush, REPORT_PUSH_MS);
+    const logError = (system, message) => {
+        devtools.logs.write("error", system, message);
+        // An error is the one line that must not wait for the next tick: a crash can tear
+        // the presentation down (or trigger a reload) before an idle callback ever runs.
+        if (shouldPush)
+            void pushOnce();
+    };
+    const onError = (event) => {
+        logError("runtime", `${event.message} (${event.filename ?? "?"}:${event.lineno ?? 0})`);
+    };
+    const onRejection = (event) => {
+        const reason = event.reason;
+        const message = reason instanceof Error ? `${reason.name}: ${reason.message}` : String(reason);
+        logError("runtime", `unhandled rejection: ${message}`);
+    };
+    const onContextLost = (event) => {
+        const target = event.target;
+        const where = target?.id !== undefined && target.id.length > 0 ? `#${target.id}` : "canvas";
+        logError("render", `webgl context lost on ${where}`);
+    };
+    window.addEventListener("error", onError);
+    window.addEventListener("unhandledrejection", onRejection);
+    document.addEventListener("webglcontextlost", onContextLost, true);
+    window.__JG = { report: buildReport };
+    installed = telemetry;
+    if (!shouldPush)
+        clearInterval(timer);
+    return telemetry;
+}
+function scheduleIdle(run) {
+    const idle = window;
+    if (typeof idle.requestIdleCallback === "function")
+        return idle.requestIdleCallback(run, { timeout: REPORT_PUSH_MS });
+    return window.setTimeout(run, 0);
+}
+function cancelIdle(handle) {
+    const idle = window;
+    if (typeof idle.cancelIdleCallback === "function")
+        idle.cancelIdleCallback(handle);
+    else
+        window.clearTimeout(handle);
+}

package/dist/environment/AuthoredDaylight.d.ts

@@ -0,0 +1,28 @@
+import type { SkyEnvironmentDescriptor } from "@jgengine/core/world/features";
+import type { DaylightModulation } from "../render/SceneLighting.js";
+/** Props for {@link AuthoredDaylight}: the authored sky whose values are the noon keyframe, the world clock, and the holder configured lights read. */
+export interface AuthoredDaylightProps {
+    /** The authored sky; its `sunIntensity`/`ambientIntensity` are the noon peak the cycle scales from. */
+    sky: SkyEnvironmentDescriptor;
+    /** The world's `SimClock` (or a stub exposing `calendar().dayFraction`). */
+    clock: {
+        calendar(): {
+            dayFraction: number;
+        };
+    };
+    /** Mutable holder the shell's configured lights read every frame. */
+    modulation: DaylightModulation;
+}
+/**
+ * Drives authored `PlayableGame.lighting` from the day cycle: it scales the first directional (the
+ * sun) and the ambient fill between the authored noon peak and night, retints the sun, and mounts
+ * the moon. Without it a time-of-day sky only repaints the dome, so the ground keeps its midday key
+ * light after dark — a black sky over a sunlit city.
+ *
+ * The authored values stay the noon keyframe, mirroring how `horizonColor`/`zenithColor` already
+ * work, so art direction still owns how bright noon is.
+ *
+ * @capability day-night-sky let an authored sun set and a moon rise instead of a fixed midday key light
+ * @internal
+ */
+export declare function AuthoredDaylight({ sky, clock, modulation }: AuthoredDaylightProps): import("react").JSX.Element | null;

package/dist/environment/AuthoredDaylight.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useMemo, useRef } from "react";
+import * as THREE from "three";
+import { MoonLight, useMoonAboveHorizon } from "./Daylight.js";
+import { daylightStateAt, DEFAULT_DAY_AMBIENT_INTENSITY, DEFAULT_DAY_SUN_INTENSITY } from "./daylightCycle.js";
+/**
+ * Drives authored `PlayableGame.lighting` from the day cycle: it scales the first directional (the
+ * sun) and the ambient fill between the authored noon peak and night, retints the sun, and mounts
+ * the moon. Without it a time-of-day sky only repaints the dome, so the ground keeps its midday key
+ * light after dark — a black sky over a sunlit city.
+ *
+ * The authored values stay the noon keyframe, mirroring how `horizonColor`/`zenithColor` already
+ * work, so art direction still owns how bright noon is.
+ *
+ * @capability day-night-sky let an authored sun set and a moon rise instead of a fixed midday key light
+ * @internal
+ */
+export function AuthoredDaylight({ sky, clock, modulation }) {
+    const initial = useMemo(() => daylightStateAt(clock.calendar().dayFraction, sky), [sky, clock]);
+    const noonSun = sky.sunIntensity ?? DEFAULT_DAY_SUN_INTENSITY;
+    const noonAmbient = sky.ambientIntensity ?? DEFAULT_DAY_AMBIENT_INTENSITY;
+    const moonRef = useRef(null);
+    const moonDirectionRef = useRef(initial.moonPosition);
+    const [moonUp, syncMoon] = useMoonAboveHorizon(initial.moonIntensity > 0);
+    useFrame(() => {
+        const state = daylightStateAt(clock.calendar().dayFraction, sky);
+        modulation.sunFactor = state.sunIntensity / noonSun;
+        modulation.sunColor = state.sunColor;
+        modulation.ambientFactor = state.ambientIntensity / noonAmbient;
+        moonDirectionRef.current = state.moonPosition;
+        const moon = moonRef.current;
+        if (moon !== null) {
+            moon.intensity = state.moonIntensity;
+            moon.color.set(state.moonColor);
+        }
+        syncMoon(state.moonIntensity);
+    });
+    if (!moonUp)
+        return null;
+    return (_jsx(MoonLight, { direction: initial.moonPosition, directionRef: moonDirectionRef, lightRef: moonRef, intensity: initial.moonIntensity, color: initial.moonColor }));
+}

package/dist/environment/Daylight.d.ts

@@ -14,6 +14,14 @@ export interface SkyDomeProps {
     sunColor?: string;
     /** Sun disc/glow intensity multiplier. Default 1. */
     sunIntensity?: number;
+    /** Direction toward the moon; a cool disc + halo is drawn there at night. Omit to skip the moon. */
+    moonDirection?: readonly [number, number, number];
+    /** Moon disc/halo colour. Default cool moonlight. */
+    moonColor?: string;
+    /** Moon disc/halo intensity multiplier. Default 0 (no moon). */
+    moonIntensity?: number;
+    /** Star-field opacity: 0 is a day sky, 1 is a clear night. Default 0. */
+    starOpacity?: number;
     /** Horizon haze-band strength: 0 removes the dusty band, ~1 makes it heavy. Default 0.5. */
     hazeStrength?: number;
     /** Procedural cloud-band opacity: 0 is a clear sky, 1 is heavy overcast. Default 0.35. */
@@ -23,13 +31,29 @@ export interface SkyDomeProps {
     /** 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>;
 }
+/** Aim the dome's moon disc and dial its brightness; called per frame by the time-of-day drivers. @internal */
+export declare function setSkyMoon(material: THREE.ShaderMaterial, direction: readonly [number, number, number], color: THREE.ColorRepresentation, intensity: number, starOpacity: number): void;
 /**
  * Shadow-casting sun whose shadow box leads the camera each frame ({@link sunShadowFocus}), so
  * grounded shadows stay crisp and soft-edged under the player anywhere in a large world. Time-of-day
  * drivers aim it through `directionRef` and retint it through `lightRef`.
  * @internal
  */
-export declare function SunLight({ direction, directionRef, lightRef, intensity, color, }: {
+export declare function SunLight({ direction, directionRef, lightRef, intensity, color, castShadow, }: {
+    direction: readonly [number, number, number];
+    directionRef?: MutableRefObject<readonly [number, number, number]>;
+    lightRef?: RefObject<THREE.DirectionalLight | null>;
+    intensity: number;
+    color: string;
+    /** Shadow-casting key light. Off for the moon: its light is too weak to read a shadow and a second shadow pass is not free. */
+    castShadow?: boolean;
+}): import("react").JSX.Element;
+/**
+ * The moon as a dim, shadowless key light opposite the sun, so a night scene keeps a lit and a
+ * shaded side instead of collapsing into flat ambient. Same camera-following aim as the sun.
+ * @internal
+ */
+export declare function MoonLight({ direction, directionRef, lightRef, intensity, color }: {
     direction: readonly [number, number, number];
     directionRef?: MutableRefObject<readonly [number, number, number]>;
     lightRef?: RefObject<THREE.DirectionalLight | null>;
@@ -58,7 +82,7 @@ export declare function SkyFog({ color, near, far, fogRef }: {
 /** Sets the display color a {@link SkyFog} converts each frame. @internal */
 export declare function setSkyFogColor(fog: THREE.Fog, color: THREE.ColorRepresentation): void;
 /** @internal */
-export declare function SkyDome({ topColor, horizonColor, radius, offset, exponent, sunDirection, sunColor, sunIntensity, hazeStrength, sunGlowStrength, cloudiness, materialRef, }?: SkyDomeProps): import("react").JSX.Element;
+export declare function SkyDome({ topColor, horizonColor, radius, offset, exponent, sunDirection, sunColor, sunIntensity, moonDirection, moonColor, moonIntensity, starOpacity, hazeStrength, sunGlowStrength, cloudiness, materialRef, }?: SkyDomeProps): import("react").JSX.Element;
 export interface DaylightProps {
     sky?: SkyDomeProps | false;
     fog?: {
@@ -71,6 +95,12 @@ export interface DaylightProps {
         intensity?: number;
         color?: string;
     };
+    moon?: {
+        position?: readonly [number, number, number];
+        intensity?: number;
+        color?: string;
+        stars?: number;
+    };
     ambient?: {
         skyColor?: string;
         groundColor?: string;
@@ -82,17 +112,29 @@ export interface DaylightProps {
     clouds?: VolumetricCloudsConfig;
 }
 /** @internal */
-export declare function Daylight({ sky, fog, sun, ambient, lights, clouds }?: DaylightProps): import("react").JSX.Element;
+export declare function Daylight({ sky, fog, sun, ambient, moon, lights, clouds }?: DaylightProps): import("react").JSX.Element;
 export interface SkyDaylightProps {
     sky: SkyEnvironmentDescriptor;
     lights?: boolean;
-    /** Terrain `biomeBands`; when any carries `fog`/`sky`, fog and dome cross-fade per camera z. */
+    /** Terrain `biomeBands`; when any carries `fog`/`sky`, fog and cross-fade per camera z. */
     bands?: readonly BiomeBand[];
+    /** Fog range authored on the game's `backdrop.fog`, used when the sky descriptor sets none. */
+    fogRange?: {
+        near?: number;
+        far?: number;
+    };
 }
+/**
+ * Mount state for the moon: it re-renders only when the moon crosses the horizon. A zero-intensity
+ * directional light still costs a per-fragment loop in every lit material, so a day sky must not
+ * carry it.
+ * @internal
+ */
+export declare function useMoonAboveHorizon(initialUp: boolean): [boolean, (intensity: number) => void];
 /** 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.
  * @internal
  */
-export declare function SkyDaylight({ sky, lights, bands }: SkyDaylightProps): import("react").JSX.Element;
+export declare function SkyDaylight({ sky, lights, bands, fogRange }: SkyDaylightProps): import("react").JSX.Element;
 export interface TimeOfDayDaylightProps {
     sky: SkyEnvironmentDescriptor;
     /** The world's `SimClock` (or a stub exposing `calendar().dayFraction`). Absent means static rendering. */
@@ -104,11 +146,17 @@ export interface TimeOfDayDaylightProps {
     lights?: boolean;
     /** Terrain `biomeBands`; when any carries `fog`/`sky`, fog and dome cross-fade per camera z. */
     bands?: readonly BiomeBand[];
+    /** Fog range authored on the game's `backdrop.fog`, used when the sky descriptor sets none. */
+    fogRange?: {
+        near?: number;
+        far?: number;
+    };
 }
 /**
  * Drives sky/fog (and optional default lights) from the world clock when `sky.timeOfDay` and `clock`
  * are both present. Authored `PlayableGame.lighting` is never rewritten — pass `lights={false}` so
- * only dome colors and fog track the day fraction.
+ * only dome colors and fog track the day fraction; `AuthoredDaylight` scales those authored lights
+ * from the same state.
   * @internal
   */
-export declare function TimeOfDayDaylight({ sky, clock, lights, bands }: TimeOfDayDaylightProps): import("react").JSX.Element;
+export declare function TimeOfDayDaylight({ sky, clock, lights, bands, fogRange }: TimeOfDayDaylightProps): import("react").JSX.Element;