@jgengine/core 0.10.0 → 0.12.0

package/dist/devtools/frame.js

@@ -0,0 +1,247 @@
+const FRAME_CAPACITY = 240;
+const RECENT_FRAMES = 60;
+/** Frame duration in milliseconds above which a frame is recorded as a long-frame spike (~30fps budget). */
+export const LONG_FRAME_MS = 33.4;
+const LONG_FRAME_CAPACITY = 40;
+const MAX_PHASES_PER_FRAME = 24;
+const MAX_LONG_FRAME_PHASES = 8;
+const PHASE_HOT_MS = 2;
+/** @internal */
+export function nowMs() {
+    const perf = globalThis.performance;
+    return perf !== undefined ? perf.now() : Date.now();
+}
+function percentile(sorted, fraction) {
+    if (sorted.length === 0)
+        return 0;
+    const index = Math.min(sorted.length - 1, Math.floor(sorted.length * fraction));
+    return sorted[index];
+}
+function clampMs(value) {
+    return value > 0 && Number.isFinite(value) ? value : 0;
+}
+function rankPhases(phases) {
+    const entries = Object.entries(phases)
+        .filter(([, ms]) => Number.isFinite(ms) && ms > 0)
+        .map(([name, ms]) => ({ name, ms }))
+        .sort((a, b) => b.ms - a.ms)
+        .slice(0, MAX_LONG_FRAME_PHASES);
+    const total = entries.reduce((sum, entry) => sum + entry.ms, 0);
+    return entries.map((entry) => ({
+        name: entry.name,
+        ms: entry.ms,
+        pct: total > 0 ? (entry.ms / total) * 100 : 0,
+    }));
+}
+function explainLongFrame(frameMs, simMs, outsideMs, ranked) {
+    const top = ranked[0] ?? null;
+    const topPhaseMs = top?.ms ?? 0;
+    const phaseBits = ranked
+        .filter((entry) => entry.ms >= PHASE_HOT_MS)
+        .slice(0, 3)
+        .map((entry) => `${entry.name} ${entry.ms.toFixed(1)}ms`);
+    const outsideDominates = outsideMs > topPhaseMs && outsideMs >= simMs * 0.55 && outsideMs >= frameMs * 0.4;
+    if (outsideDominates) {
+        const detail = phaseBits.length > 0 ? ` · sim was ${phaseBits.join(", ")}` : simMs > 1 ? ` · sim ${simMs.toFixed(1)}ms` : "";
+        return {
+            topPhase: top?.name ?? null,
+            culprit: "outside-sim",
+            reason: `display/render/browser hitch ${outsideMs.toFixed(1)}ms outside sim${detail}`,
+        };
+    }
+    if (top !== null && top.ms >= PHASE_HOT_MS) {
+        const rest = phaseBits.slice(1);
+        const restText = rest.length > 0 ? ` · also ${rest.join(", ")}` : "";
+        const outsideText = outsideMs >= PHASE_HOT_MS ? ` · +${outsideMs.toFixed(1)}ms outside sim` : "";
+        return {
+            topPhase: top.name,
+            culprit: top.name,
+            reason: `${top.name} ${top.ms.toFixed(1)}ms (${top.pct.toFixed(0)}% of timed sim)${restText}${outsideText}`,
+        };
+    }
+    if (simMs >= frameMs * 0.5) {
+        return {
+            topPhase: null,
+            culprit: "sim",
+            reason: `sim ${simMs.toFixed(1)}ms with no named phase ≥${PHASE_HOT_MS}ms — wrap hot work in measure("name", fn)`,
+        };
+    }
+    return {
+        topPhase: null,
+        culprit: "outside-sim",
+        reason: `frame ${frameMs.toFixed(1)}ms · sim ${simMs.toFixed(1)}ms · outside ${outsideMs.toFixed(1)}ms (render/React/GC/tab throttle)`,
+    };
+}
+/** Create the frame subsystem that records frame/sim/phase timings, computes stats, and captures long-frame events. */
+export const createFrameModule = (deps) => {
+    const { readProbes } = deps;
+    const frameMsBuffer = new Float64Array(FRAME_CAPACITY);
+    const simMsBuffer = new Float64Array(FRAME_CAPACITY);
+    const outsideMsBuffer = new Float64Array(FRAME_CAPACITY);
+    let frameIndex = 0;
+    let frameCount = 0;
+    let renderSample = null;
+    const longFrameEvents = [];
+    const phaseAccumulators = new Map();
+    let currentPhases = {};
+    let currentPhaseCount = 0;
+    const addPhaseMs = (name, ms) => {
+        const elapsed = clampMs(ms);
+        if (elapsed === 0 || name.length === 0)
+            return;
+        if (currentPhases[name] === undefined) {
+            if (currentPhaseCount >= MAX_PHASES_PER_FRAME)
+                return;
+            currentPhaseCount += 1;
+            currentPhases[name] = elapsed;
+            return;
+        }
+        currentPhases[name] = currentPhases[name] + elapsed;
+    };
+    const resetCurrentPhases = () => {
+        currentPhases = {};
+        currentPhaseCount = 0;
+    };
+    const recordPhaseStats = (phases) => {
+        for (const [name, ms] of Object.entries(phases)) {
+            const elapsed = clampMs(ms);
+            if (elapsed === 0)
+                continue;
+            const existing = phaseAccumulators.get(name);
+            if (existing === undefined) {
+                phaseAccumulators.set(name, { sumMs: elapsed, maxMs: elapsed, lastMs: elapsed, samples: 1 });
+            }
+            else {
+                existing.sumMs += elapsed;
+                existing.maxMs = Math.max(existing.maxMs, elapsed);
+                existing.lastMs = elapsed;
+                existing.samples += 1;
+            }
+        }
+    };
+    const phaseStatsList = (avgSimMs) => {
+        const list = [];
+        for (const [name, acc] of phaseAccumulators) {
+            const avgMs = acc.sumMs / acc.samples;
+            list.push({
+                name,
+                avgMs,
+                maxMs: acc.maxMs,
+                lastMs: acc.lastMs,
+                samples: acc.samples,
+                pctOfSim: avgSimMs > 0 ? (avgMs / avgSimMs) * 100 : 0,
+            });
+        }
+        list.sort((a, b) => b.avgMs - a.avgMs);
+        return list;
+    };
+    const frameStats = () => {
+        if (frameCount === 0)
+            return null;
+        const size = Math.min(frameCount, FRAME_CAPACITY);
+        const frames = [];
+        const sims = [];
+        const outsides = [];
+        for (let offset = 0; offset < size; offset += 1) {
+            const at = (frameIndex - size + offset + FRAME_CAPACITY) % FRAME_CAPACITY;
+            frames.push(frameMsBuffer[at]);
+            sims.push(simMsBuffer[at]);
+            outsides.push(outsideMsBuffer[at]);
+        }
+        const recent = frames.slice(-RECENT_FRAMES);
+        const recentAvg = recent.reduce((sum, ms) => sum + ms, 0) / recent.length;
+        const sorted = [...frames].sort((a, b) => a - b);
+        const avgSimMs = sims.reduce((sum, ms) => sum + ms, 0) / sims.length;
+        return {
+            fps: recentAvg > 0 ? 1000 / recentAvg : 0,
+            avgFrameMs: frames.reduce((sum, ms) => sum + ms, 0) / frames.length,
+            p95FrameMs: percentile(sorted, 0.95),
+            maxFrameMs: sorted[sorted.length - 1],
+            avgSimMs,
+            maxSimMs: sims.reduce((max, ms) => Math.max(max, ms), 0),
+            avgOutsideMs: outsides.reduce((sum, ms) => sum + ms, 0) / outsides.length,
+            maxOutsideMs: outsides.reduce((max, ms) => Math.max(max, ms), 0),
+            longFrames: frames.filter((ms) => ms > LONG_FRAME_MS).length,
+            samples: size,
+            recentFrameMs: recent,
+            phases: phaseStatsList(avgSimMs),
+        };
+    };
+    const recordFrame = (sample) => {
+        const frameMs = clampMs(sample.frameMs);
+        const simMs = clampMs(sample.simMs);
+        const outsideMs = clampMs(frameMs - simMs);
+        const phases = sample.phases !== undefined
+            ? Object.fromEntries(Object.entries(sample.phases)
+                .filter(([, ms]) => Number.isFinite(ms) && ms > 0)
+                .slice(0, MAX_PHASES_PER_FRAME))
+            : { ...currentPhases };
+        frameMsBuffer[frameIndex] = frameMs;
+        simMsBuffer[frameIndex] = simMs;
+        outsideMsBuffer[frameIndex] = outsideMs;
+        frameIndex = (frameIndex + 1) % FRAME_CAPACITY;
+        frameCount += 1;
+        recordPhaseStats(phases);
+        if (frameMs > LONG_FRAME_MS) {
+            const ranked = rankPhases(phases);
+            const explained = explainLongFrame(frameMs, simMs, outsideMs, ranked);
+            longFrameEvents.push({
+                at: Date.now(),
+                frameMs,
+                simMs,
+                outsideMs,
+                phases: ranked,
+                topPhase: explained.topPhase,
+                culprit: explained.culprit,
+                reason: explained.reason,
+                probes: readProbes(),
+                render: renderSample,
+            });
+            if (longFrameEvents.length > LONG_FRAME_CAPACITY) {
+                longFrameEvents.splice(0, longFrameEvents.length - LONG_FRAME_CAPACITY);
+            }
+        }
+        resetCurrentPhases();
+    };
+    return {
+        frame: {
+            record: recordFrame,
+            stats: frameStats,
+            longFrames: () => longFrameEvents,
+            clearLongFrames() {
+                longFrameEvents.length = 0;
+            },
+            reset() {
+                frameIndex = 0;
+                frameCount = 0;
+                longFrameEvents.length = 0;
+                phaseAccumulators.clear();
+                resetCurrentPhases();
+            },
+        },
+        profile: {
+            begin(name) {
+                const start = nowMs();
+                return () => addPhaseMs(name, nowMs() - start);
+            },
+            measure(name, fn) {
+                const start = nowMs();
+                try {
+                    return fn();
+                }
+                finally {
+                    addPhaseMs(name, nowMs() - start);
+                }
+            },
+            add: addPhaseMs,
+            current: () => ({ ...currentPhases }),
+            reset: resetCurrentPhases,
+        },
+        render: {
+            record(sample) {
+                renderSample = sample;
+            },
+            latest: () => renderSample,
+        },
+    };
+};

package/dist/devtools/logs.d.ts

@@ -0,0 +1,15 @@
+import type { ChangeSignal } from "../store/changeSignal.js";
+import type { Devtools } from "./types.js";
+/** @internal */
+export declare function formatLogArg(arg: unknown): string;
+/** Format an array of console arguments into a single truncated log message string. */
+export declare function formatLogMessage(args: readonly unknown[]): string;
+/** Logs subsystem exposing the log-capture and latency-tracking facades. */
+export interface LogsModule {
+    logs: Devtools["logs"];
+    latency: Devtools["latency"];
+}
+/** Create the logs subsystem that buffers captured console output and records latency samples. */
+export declare const createLogsModule: (deps: {
+    signal: ChangeSignal;
+}) => LogsModule;

package/dist/devtools/logs.js

@@ -0,0 +1,86 @@
+const LATENCY_CAPACITY = 120;
+const LOG_CAPACITY = 200;
+const LOG_MESSAGE_MAX = 400;
+/** @internal */
+export function formatLogArg(arg) {
+    if (typeof arg === "string")
+        return arg;
+    if (arg instanceof Error)
+        return `${arg.name}: ${arg.message}`;
+    try {
+        return JSON.stringify(arg) ?? String(arg);
+    }
+    catch {
+        return String(arg);
+    }
+}
+/** Format an array of console arguments into a single truncated log message string. */
+export function formatLogMessage(args) {
+    const message = args.map(formatLogArg).join(" ");
+    return message.length > LOG_MESSAGE_MAX ? `${message.slice(0, LOG_MESSAGE_MAX)}…` : message;
+}
+/** Create the logs subsystem that buffers captured console output and records latency samples. */
+export const createLogsModule = (deps) => {
+    const { signal } = deps;
+    const logEntries = [];
+    let consoleCaptured = false;
+    const latencySamples = [];
+    const pushLog = (level, message) => {
+        logEntries.push({ at: Date.now(), level, message });
+        if (logEntries.length > LOG_CAPACITY)
+            logEntries.splice(0, logEntries.length - LOG_CAPACITY);
+    };
+    const latencyStats = () => {
+        if (latencySamples.length === 0)
+            return null;
+        let min = Number.POSITIVE_INFINITY;
+        let max = 0;
+        let sum = 0;
+        for (const ms of latencySamples) {
+            min = Math.min(min, ms);
+            max = Math.max(max, ms);
+            sum += ms;
+        }
+        return {
+            lastMs: latencySamples[latencySamples.length - 1],
+            avgMs: sum / latencySamples.length,
+            minMs: min,
+            maxMs: max,
+            samples: latencySamples.length,
+        };
+    };
+    return {
+        logs: {
+            push: pushLog,
+            captureConsole() {
+                if (consoleCaptured)
+                    return;
+                const globalConsole = globalThis.console;
+                if (globalConsole === undefined)
+                    return;
+                consoleCaptured = true;
+                const levels = ["log", "info", "warn", "error"];
+                for (const level of levels) {
+                    const original = globalConsole[level].bind(globalConsole);
+                    globalConsole[level] = (...args) => {
+                        pushLog(level, formatLogMessage(args));
+                        original(...args);
+                    };
+                }
+            },
+            list: () => logEntries,
+            clear() {
+                logEntries.length = 0;
+                signal.notify();
+            },
+        },
+        latency: {
+            record(ms) {
+                latencySamples.push(ms);
+                if (latencySamples.length > LATENCY_CAPACITY)
+                    latencySamples.splice(0, latencySamples.length - LATENCY_CAPACITY);
+            },
+            stats: latencyStats,
+        },
+    };
+};

package/dist/devtools/overrides.d.ts

@@ -0,0 +1,16 @@
+import type { ChangeSignal } from "../store/changeSignal.js";
+import { type ControlRecord } from "./controls.js";
+import type { DiscoveredRecord } from "./discover.js";
+import type { Devtools } from "./types.js";
+/** Overrides subsystem exposing the export/apply facade for persisting and restoring control values. */
+export interface OverridesModule {
+    overrides: Devtools["overrides"];
+}
+/** Create the overrides subsystem that serializes changed control values and re-applies a saved overrides payload. */
+export declare const createOverridesModule: (deps: {
+    signal: ChangeSignal;
+    controlRecords: Map<string, ControlRecord>;
+    writeControl: (record: ControlRecord, raw: unknown) => boolean;
+    discoveredRecords: Map<string, DiscoveredRecord>;
+    enableDiscovered: (id: string) => void;
+}) => OverridesModule;

package/dist/devtools/overrides.js

@@ -0,0 +1,66 @@
+import { OVERRIDES_FORMAT_VERSION, cloneValue, parseOverridesPayload, } from "./tunableSchema.js";
+import { isStructuralKind } from "./controls.js";
+/** Create the overrides subsystem that serializes changed control values and re-applies a saved overrides payload. */
+export const createOverridesModule = (deps) => {
+    const { signal, controlRecords, writeControl, discoveredRecords, enableDiscovered } = deps;
+    return {
+        overrides: {
+            export() {
+                const enabled = [...discoveredRecords.values()].filter((r) => r.enabled).map((r) => r.id);
+                const values = {};
+                const schemas = {};
+                for (const record of controlRecords.values()) {
+                    schemas[record.name] = { kind: record.kind, schemaVersion: record.schemaVersion };
+                    const same = isStructuralKind(record.kind)
+                        ? JSON.stringify(record.value) === JSON.stringify(record.initial)
+                        : Object.is(record.value, record.initial);
+                    if (!same)
+                        values[record.name] = cloneValue(record.value);
+                }
+                return {
+                    version: OVERRIDES_FORMAT_VERSION,
+                    enabled,
+                    values,
+                    schemas,
+                };
+            },
+            apply(raw) {
+                const parsed = parseOverridesPayload(raw);
+                const diagnostics = [...parsed.diagnostics];
+                const skipped = [];
+                if (parsed.overrides === null) {
+                    return { applied: 0, skipped, diagnostics };
+                }
+                const overrides = parsed.overrides;
+                let applied = 0;
+                for (const id of overrides.enabled) {
+                    if (!discoveredRecords.has(id) && !controlRecords.has(id)) {
+                        skipped.push({ id, reason: "unknown control id" });
+                        continue;
+                    }
+                    enableDiscovered(id);
+                    applied += 1;
+                }
+                for (const [name, value] of Object.entries(overrides.values)) {
+                    const record = controlRecords.get(name);
+                    if (record === undefined) {
+                        skipped.push({ id: name, reason: "control not registered" });
+                        continue;
+                    }
+                    const schema = overrides.schemas?.[name];
+                    if (schema !== undefined && schema.kind !== record.kind) {
+                        skipped.push({ id: name, reason: `kind mismatch stored=${schema.kind} current=${record.kind}` });
+                        continue;
+                    }
+                    if (!writeControl(record, value)) {
+                        skipped.push({ id: name, reason: "value failed validation" });
+                        continue;
+                    }
+                    applied += 1;
+                }
+                signal.notify();
+                return { applied, skipped, diagnostics };
+            },
+        },
+    };
+};

package/dist/devtools/rewriteTunables.d.ts

@@ -0,0 +1,17 @@
+/** One changed tunable to write back into game source: which table, key path, and new value. */
+export interface TunableDelta {
+    table: string;
+    key: string;
+    value: unknown;
+}
+/** Renders a tunable value as TS source, or null when the value has no safe literal form.
+ * @internal
+ */
+export declare function formatTunableLiteral(value: unknown): string | null;
+/**
+ * Rewrites one tunable's literal inside TS source: `exportName` names the `export const/let`,
+ * `path` descends object keys and array indices to the scalar, and `value` becomes the new
+ * literal. Returns the updated source, or null when the target cannot be safely located.
+  * @internal
+  */
+export declare function rewriteTunableExport(code: string, exportName: string, path: readonly string[], value: unknown): string | null;