@jgengine/core 0.11.0 → 0.13.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/types.d.ts

@@ -0,0 +1,212 @@
+import type { ChangeSignal } from "../store/changeSignal.js";
+import type { AngleUnit, DevtoolsControlKind, DevtoolsOverrides, DiscoverySkip, OverrideApplyDiagnostic, ScanMeta, TunableChoice, TunableOptions } from "./tunableSchema.js";
+/** Registered tunable control with its resolved schema metadata and read/write/reset accessors. */
+export interface DevtoolsControl {
+    readonly name: string;
+    readonly kind: DevtoolsControlKind;
+    readonly label: string;
+    readonly group: string;
+    readonly initial: unknown;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+    readonly options?: readonly unknown[];
+    readonly choices?: readonly TunableChoice[];
+    readonly unit?: AngleUnit;
+    readonly displayUnit?: AngleUnit;
+    readonly wrap?: boolean;
+    readonly integer?: boolean;
+    readonly axisLabels?: readonly string[];
+    readonly axisMin?: readonly number[];
+    readonly axisMax?: readonly number[];
+    readonly axisStep?: readonly number[];
+    readonly hasAlpha?: boolean;
+    readonly schemaVersion: number;
+    read(): unknown;
+    write(value: unknown): boolean;
+    reset(): void;
+}
+/** Typed handle to a registered control, exposing its live value and subscribe/set/reset operations. */
+export interface Tunable<T> {
+    readonly name: string;
+    readonly kind: DevtoolsControlKind;
+    readonly initial: T;
+    readonly value: T;
+    set(value: T): boolean;
+    reset(): void;
+    subscribe(listener: (value: T) => void): () => void;
+}
+/** Outcome of applying a devtools overrides payload: counts of applied and skipped entries plus diagnostics. */
+export interface OverrideApplyResult {
+    applied: number;
+    skipped: readonly OverrideApplyDiagnostic[];
+    diagnostics: readonly string[];
+}
+/** Aggregated frame-timing statistics over the recent sampling window, including per-phase breakdown. */
+export interface FrameStats {
+    fps: number;
+    avgFrameMs: number;
+    p95FrameMs: number;
+    maxFrameMs: number;
+    avgSimMs: number;
+    maxSimMs: number;
+    avgOutsideMs: number;
+    maxOutsideMs: number;
+    longFrames: number;
+    samples: number;
+    recentFrameMs: readonly number[];
+    phases: readonly PhaseStats[];
+}
+/** Timing summary for a single named profiling phase across the sampling window. */
+export interface PhaseStats {
+    name: string;
+    avgMs: number;
+    maxMs: number;
+    lastMs: number;
+    samples: number;
+    pctOfSim: number;
+}
+/** Recorded spike event for a frame that exceeded the long-frame threshold, with culprit attribution. */
+export interface LongFrameEvent {
+    at: number;
+    frameMs: number;
+    simMs: number;
+    outsideMs: number;
+    phases: readonly {
+        name: string;
+        ms: number;
+        pct: number;
+    }[];
+    topPhase: string | null;
+    culprit: string;
+    reason: string;
+    probes: Record<string, unknown>;
+    render: RenderSample | null;
+}
+/** Snapshot of renderer resource counts (draw calls, triangles, geometries, textures) for a frame. */
+export interface RenderSample {
+    drawCalls: number;
+    triangles: number;
+    geometries: number;
+    textures: number;
+}
+/** Aggregated latency statistics (last/avg/min/max) over recorded latency samples. */
+export interface LatencyStats {
+    lastMs: number;
+    avgMs: number;
+    minMs: number;
+    maxMs: number;
+    samples: number;
+}
+/** Severity level for a captured devtools log entry. */
+export type DevtoolsLogLevel = "log" | "info" | "warn" | "error";
+/** A single captured log line with timestamp, level, and formatted message. */
+export interface DevtoolsLogEntry {
+    at: number;
+    level: DevtoolsLogLevel;
+    message: string;
+}
+/** A control auto-discovered by scanning an object/table, with its binding metadata and current reader. */
+export interface DiscoveredEntry {
+    readonly id: string;
+    readonly table: string;
+    readonly key: string;
+    readonly kind: DevtoolsControlKind;
+    readonly initial: unknown;
+    readonly enabled: boolean;
+    read(): unknown;
+}
+/** Get/set accessor pair plus initial value used to bind a discovered field to a control. */
+export interface TunableAccessor {
+    initial: unknown;
+    get(): unknown;
+    set(value: unknown): void;
+}
+/** Serializable point-in-time snapshot of devtools state: frame, render, latency, logs, controls, and discovered fields. */
+export interface DevtoolsSnapshot {
+    at: number;
+    frame: FrameStats | null;
+    render: RenderSample | null;
+    latency: LatencyStats | null;
+    longFrames: readonly LongFrameEvent[];
+    logs: readonly DevtoolsLogEntry[];
+    probes: Record<string, unknown>;
+    controls: readonly {
+        name: string;
+        kind: DevtoolsControlKind;
+        value: unknown;
+        initial: unknown;
+    }[];
+    discovered: readonly {
+        id: string;
+        kind: DevtoolsControlKind;
+        value: unknown;
+        enabled: boolean;
+    }[];
+    skipped: readonly DiscoverySkip[];
+}
+/** Per-frame timing input recorded by callers: total frame time, sim time, and optional named phase durations. */
+export interface FrameRecordSample {
+    frameMs: number;
+    simMs: number;
+    phases?: Readonly<Record<string, number>>;
+}
+/** Top-level devtools facade aggregating frame, profile, render, logs, latency, controls, discover, overrides, and probes. */
+export interface Devtools {
+    frame: {
+        record(sample: FrameRecordSample): void;
+        stats(): FrameStats | null;
+        longFrames(): readonly LongFrameEvent[];
+        clearLongFrames(): void;
+        /** Drop all frame/phase/long-frame history so the next stats() window starts clean — use after load/shader warmup before measuring. */
+        reset(): void;
+    };
+    profile: {
+        begin(name: string): () => void;
+        measure<T>(name: string, fn: () => T): T;
+        add(name: string, ms: number): void;
+        current(): Record<string, number>;
+        reset(): void;
+    };
+    render: {
+        record(sample: RenderSample): void;
+        latest(): RenderSample | null;
+    };
+    logs: {
+        push(level: DevtoolsLogLevel, message: string): void;
+        captureConsole(): void;
+        list(): readonly DevtoolsLogEntry[];
+        clear(): void;
+    };
+    latency: {
+        record(ms: number): void;
+        stats(): LatencyStats | null;
+    };
+    controls: {
+        register<T>(name: string, initial: T, options?: TunableOptions<T>): Tunable<T>;
+        list(): readonly DevtoolsControl[];
+        get(name: string): DevtoolsControl | null;
+        remove(name: string): void;
+        resetAll(): void;
+    };
+    discover: {
+        bind(table: string, key: string, accessor: TunableAccessor, options?: TunableOptions): void;
+        scanTable(table: string, candidate: unknown, meta?: ScanMeta): number;
+        scanModule(exports: Record<string, unknown>, meta?: ScanMeta): number;
+        list(): readonly DiscoveredEntry[];
+        skipped(): readonly DiscoverySkip[];
+        enable(id: string): void;
+        disable(id: string): void;
+        clear(): void;
+    };
+    overrides: {
+        export(): DevtoolsOverrides;
+        apply(overrides: DevtoolsOverrides | unknown): OverrideApplyResult;
+    };
+    probes: {
+        register(name: string, read: () => unknown): () => void;
+        read(): Record<string, unknown>;
+    };
+    signal: ChangeSignal;
+    snapshot(): DevtoolsSnapshot;
+}

package/dist/devtools/types.js

@@ -0,0 +1 @@
+export {};

package/dist/devtools/urlFlags.d.ts

@@ -0,0 +1,22 @@
+/**
+ * URL-backed debug flags — the single seam hosts use to mirror an engine debug surface (the scene
+ * editor, the devtools overlay) into the page query string. Mirroring means the URL is the honest
+ * record of what is open: share it to reproduce the state, and strip the param (then reload) to get
+ * a clean game with the surface gone. All functions no-op safely off the main browser thread.
+ */
+/** The current query value of `param`, or null when absent (or no DOM). */
+export declare function readUrlParam(param: string): string | null;
+/** True when `param` is present and not an explicit off value (`0`/`false`/`off`/`no`). */
+export declare function readUrlFlag(param: string): boolean;
+/**
+ * Sets `param` to `value`, or removes it when `value` is null, rewriting the URL in place with
+ * `history.replaceState` so the rest of the query and the hash survive and no history entry is
+ * pushed. No-ops without a DOM, and skips the write when the URL already matches.
+ */
+export declare function writeUrlParam(param: string, value: string | null): void;
+/**
+ * Fires `listener` whenever the query string may have changed out from under a flag — browser
+ * back/forward (`popstate`). Manual address-bar edits reload the page, so initial reads cover
+ * those; this keeps in-app state honest across history navigation. Returns an unsubscribe.
+ */
+export declare function subscribeUrlChange(listener: () => void): () => void;