@jgengine/core 0.11.0 → 0.13.0

package/dist/devtools/controls.js

@@ -0,0 +1,181 @@
+import { CONTROL_SCHEMA_VERSION, choiceValues, cloneValue, expandAxisMeta, inferKind, normalizeColorValue, resolveChoices, sliderBounds, validateControlValue, } from "./tunableSchema.js";
+/** @internal */
+export function isStructuralKind(kind) {
+    return kind === "vec2" || kind === "vec3" || kind === "vec4" || kind === "interval";
+}
+/** Create the controls subsystem that registers, validates, and mutates tunable controls, notifying on change. */
+export const createControlsModule = (deps) => {
+    const { signal } = deps;
+    const controlRecords = new Map();
+    const validationContext = (record) => ({
+        min: record.min,
+        max: record.max,
+        step: record.step,
+        integer: record.integer,
+        unit: record.unit,
+        wrap: record.wrap,
+        choices: record.choices,
+        options: record.options,
+        axisBounds: record.axisBounds,
+        alpha: record.hasAlpha,
+    });
+    const toControl = (record) => ({
+        name: record.name,
+        kind: record.kind,
+        label: record.label,
+        group: record.group,
+        initial: record.initial,
+        min: record.min,
+        max: record.max,
+        step: record.step,
+        options: record.options ?? choiceValues(record.choices),
+        choices: record.choices,
+        unit: record.unit,
+        displayUnit: record.displayUnit,
+        wrap: record.wrap,
+        integer: record.integer,
+        axisLabels: record.axisBounds?.labels,
+        axisMin: record.axisBounds?.min,
+        axisMax: record.axisBounds?.max,
+        axisStep: record.axisBounds?.step,
+        hasAlpha: record.hasAlpha,
+        schemaVersion: record.schemaVersion,
+        read: () => record.value,
+        write: (value) => writeControl(record, value),
+        reset: () => {
+            writeControl(record, cloneValue(record.initial));
+        },
+    });
+    const writeControl = (record, raw) => {
+        const validated = validateControlValue(record.kind, raw, validationContext(record));
+        if (!validated.ok)
+            return false;
+        const next = validated.value;
+        if (isStructuralKind(record.kind)) {
+            if (JSON.stringify(record.value) === JSON.stringify(next))
+                return true;
+            record.value = cloneValue(next);
+        }
+        else {
+            if (Object.is(record.value, next))
+                return true;
+            record.value = next;
+        }
+        for (const listener of record.listeners)
+            listener(record.value);
+        signal.notify();
+        return true;
+    };
+    const hydrateRecord = (record, initial, options, kind) => {
+        record.kind = kind;
+        record.initial = cloneValue(initial);
+        record.min = undefined;
+        record.max = undefined;
+        record.step = undefined;
+        record.options = options?.options;
+        record.choices = resolveChoices(options?.options, options?.choices);
+        record.unit = options?.unit;
+        record.displayUnit = options?.displayUnit ?? options?.unit;
+        record.wrap = options?.wrap;
+        record.integer = options?.integer;
+        record.axisBounds = undefined;
+        record.hasAlpha = undefined;
+        record.schemaVersion = CONTROL_SCHEMA_VERSION;
+        if (kind === "slider" || kind === "angle") {
+            const bounds = sliderBounds(initial, options);
+            record.min = bounds.min;
+            record.max = bounds.max;
+            record.step = bounds.step;
+            if (kind === "angle") {
+                record.unit = options?.unit ?? "rad";
+                record.displayUnit = options?.displayUnit ?? "deg";
+            }
+        }
+        else if (kind === "vec2" || kind === "vec3" || kind === "vec4") {
+            const sample = Array.isArray(initial) ? initial : [];
+            record.axisBounds = expandAxisMeta(sample.length, options?.axisLabels, options?.axisMin ?? options?.min, options?.axisMax ?? options?.max, options?.axisStep ?? options?.step, sample);
+        }
+        else if (kind === "interval") {
+            record.min = options?.min;
+            record.max = options?.max;
+            record.step = options?.step;
+            record.integer = options?.integer;
+        }
+        else if (kind === "color") {
+            const normalized = normalizeColorValue(initial, options?.alpha);
+            if (normalized !== null) {
+                record.initial = normalized;
+                if (Object.is(record.value, initial) || record.value === initial) {
+                    record.value = normalized;
+                }
+                record.hasAlpha = options?.alpha === true || normalized.length === 9;
+            }
+        }
+    };
+    const register = (name, initial, options) => {
+        const kind = inferKind(initial, options);
+        const existing = controlRecords.get(name);
+        const slashIndex = name.indexOf("/");
+        const derivedGroup = slashIndex > 0 ? name.slice(0, slashIndex) : "general";
+        const derivedLabel = slashIndex > 0 ? name.slice(slashIndex + 1) : name;
+        const record = existing !== undefined && existing.kind === kind
+            ? existing
+            : {
+                name,
+                kind,
+                label: "",
+                group: "",
+                initial: cloneValue(initial),
+                value: cloneValue(initial),
+                schemaVersion: CONTROL_SCHEMA_VERSION,
+                listeners: new Set(),
+            };
+        if (existing === undefined || existing.kind !== kind) {
+            record.value = cloneValue(initial);
+        }
+        record.label = options?.label ?? derivedLabel;
+        record.group = options?.group ?? derivedGroup;
+        hydrateRecord(record, initial, options, kind);
+        if (options?.onChange !== undefined)
+            record.listeners.add(options.onChange);
+        controlRecords.set(name, record);
+        signal.notify();
+        return {
+            name,
+            kind,
+            initial: record.initial,
+            get value() {
+                return record.value;
+            },
+            set: (value) => writeControl(record, value),
+            reset: () => {
+                writeControl(record, cloneValue(record.initial));
+            },
+            subscribe: (listener) => {
+                record.listeners.add(listener);
+                return () => record.listeners.delete(listener);
+            },
+        };
+    };
+    return {
+        controls: {
+            register,
+            list: () => [...controlRecords.values()].map(toControl),
+            get: (name) => {
+                const record = controlRecords.get(name);
+                return record === undefined ? null : toControl(record);
+            },
+            remove(name) {
+                if (controlRecords.delete(name))
+                    signal.notify();
+            },
+            resetAll() {
+                for (const record of controlRecords.values())
+                    writeControl(record, cloneValue(record.initial));
+            },
+        },
+        register,
+        writeControl,
+        controlRecords,
+    };
+};

package/dist/devtools/devtools.d.ts

@@ -1,202 +1,10 @@
-import { type ChangeSignal } from "../store/changeSignal.js";
-import { type AngleUnit, type DevtoolsControlKind, type DevtoolsOverrides, type DiscoverySkip, type OverrideApplyDiagnostic, type ScanMeta, type TunableChoice, type TunableOptions } from "./tunableSchema.js";
+import type { TunableOptions } from "./tunableSchema.js";
+import type { Devtools, DevtoolsSnapshot, Tunable } from "./types.js";
 export type { AngleUnit, DevtoolsControlKind, DevtoolsOverrides, DiscoverySkip, OverrideApplyDiagnostic, TunableChoice, TunableInterval, TunableOptions, TunableVec2, TunableVec3, TunableVec4, ScanMeta, ScanFieldMeta, NormalizedColor, } from "./tunableSchema.js";
 export { CONTROL_SCHEMA_VERSION, OVERRIDES_FORMAT_VERSION, convertAngle, escapePathSegment, formatColor, joinTunablePath, normalizeAngle, normalizeColorValue, parseColor, parseOverridesPayload, splitTunablePath, unescapePathSegment, validateControlValue, } from "./tunableSchema.js";
-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;
-}
-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;
-}
-export interface OverrideApplyResult {
-    applied: number;
-    skipped: readonly OverrideApplyDiagnostic[];
-    diagnostics: readonly string[];
-}
-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[];
-}
-export interface PhaseStats {
-    name: string;
-    avgMs: number;
-    maxMs: number;
-    lastMs: number;
-    samples: number;
-    pctOfSim: number;
-}
-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;
-}
-export interface RenderSample {
-    drawCalls: number;
-    triangles: number;
-    geometries: number;
-    textures: number;
-}
-export interface LatencyStats {
-    lastMs: number;
-    avgMs: number;
-    minMs: number;
-    maxMs: number;
-    samples: number;
-}
-export type DevtoolsLogLevel = "log" | "info" | "warn" | "error";
-export interface DevtoolsLogEntry {
-    at: number;
-    level: DevtoolsLogLevel;
-    message: string;
-}
-export interface DiscoveredEntry {
-    readonly id: string;
-    readonly table: string;
-    readonly key: string;
-    readonly kind: DevtoolsControlKind;
-    readonly initial: unknown;
-    readonly enabled: boolean;
-    read(): unknown;
-}
-export interface TunableAccessor {
-    initial: unknown;
-    get(): unknown;
-    set(value: unknown): void;
-}
-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[];
-}
-export interface FrameRecordSample {
-    frameMs: number;
-    simMs: number;
-    phases?: Readonly<Record<string, number>>;
-}
-export interface Devtools {
-    frame: {
-        record(sample: FrameRecordSample): void;
-        stats(): FrameStats | null;
-        longFrames(): readonly LongFrameEvent[];
-        clearLongFrames(): 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;
-}
-export declare const LONG_FRAME_MS = 33.4;
-export declare function formatLogMessage(args: readonly unknown[]): string;
+export type { Devtools, DevtoolsControl, DevtoolsLogEntry, DevtoolsLogLevel, DevtoolsSnapshot, DiscoveredEntry, FrameRecordSample, FrameStats, LatencyStats, LongFrameEvent, OverrideApplyResult, PhaseStats, RenderSample, Tunable, TunableAccessor, } from "./types.js";
+export { LONG_FRAME_MS } from "./frame.js";
+export { formatLogMessage } from "./logs.js";
 export declare function createDevtools(): Devtools;
 export declare const devtools: Devtools;
 export declare function tunable<T>(name: string, initial: T, options?: TunableOptions<T>): Tunable<T>;