@jgengine/core 0.8.0 → 0.10.0

package/dist/devtools/devtools.d.ts

@@ -1,14 +1,7 @@
 import { type ChangeSignal } from "../store/changeSignal.js";
-export type DevtoolsControlKind = "slider" | "toggle" | "color" | "select" | "text";
-export interface TunableOptions<T> {
-    min?: number;
-    max?: number;
-    step?: number;
-    options?: readonly T[];
-    label?: string;
-    group?: string;
-    onChange?: (value: T) => void;
-}
+import { type AngleUnit, type DevtoolsControlKind, type DevtoolsOverrides, type DiscoverySkip, type OverrideApplyDiagnostic, type ScanMeta, type TunableChoice, type TunableOptions } from "./tunableSchema.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;
@@ -19,8 +12,19 @@ export interface DevtoolsControl {
     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): void;
+    write(value: unknown): boolean;
     reset(): void;
 }
 export interface Tunable<T> {
@@ -28,10 +32,15 @@ export interface Tunable<T> {
     readonly kind: DevtoolsControlKind;
     readonly initial: T;
     readonly value: T;
-    set(value: T): void;
+    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;
@@ -39,9 +48,36 @@ export interface FrameStats {
     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;
@@ -76,15 +112,12 @@ export interface TunableAccessor {
     get(): unknown;
     set(value: unknown): void;
 }
-export interface DevtoolsOverrides {
-    enabled: string[];
-    values: Record<string, unknown>;
-}
 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 {
@@ -99,14 +132,26 @@ export interface DevtoolsSnapshot {
         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: {
-            frameMs: number;
-            simMs: number;
-        }): void;
+        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;
@@ -130,17 +175,18 @@ export interface Devtools {
         resetAll(): void;
     };
     discover: {
-        bind(table: string, key: string, accessor: TunableAccessor): void;
-        scanTable(table: string, candidate: unknown): number;
-        scanModule(exports: Record<string, unknown>): number;
+        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): void;
+        apply(overrides: DevtoolsOverrides | unknown): OverrideApplyResult;
     };
     probes: {
         register(name: string, read: () => unknown): () => void;
@@ -149,9 +195,11 @@ export interface Devtools {
     signal: ChangeSignal;
     snapshot(): DevtoolsSnapshot;
 }
+export declare const LONG_FRAME_MS = 33.4;
 export declare function formatLogMessage(args: readonly unknown[]): string;
 export declare function createDevtools(): Devtools;
 export declare const devtools: Devtools;
 export declare function tunable<T>(name: string, initial: T, options?: TunableOptions<T>): Tunable<T>;
 export declare function snapshotDevtools(): DevtoolsSnapshot;
+export declare function measureProfile<T>(name: string, fn: () => T): T;
 export declare function instrumentLatency<T extends object>(target: T, methods: readonly (keyof T)[], record?: (ms: number) => void): T;