@jgengine/core 0.8.0 → 0.9.0

package/dist/devtools/devtools.js

@@ -1,32 +1,20 @@
 import { createChangeSignal } from "../store/changeSignal.js";
+import { CONTROL_SCHEMA_VERSION, MAX_SCAN_DEPTH, MAX_SCAN_TARGETS, MAX_TABLE_ENTRIES, OVERRIDES_FORMAT_VERSION, choiceValues, cloneValue, discoverableKind, expandAxisMeta, inferKind, isScannableContainer, joinTunablePath, normalizeColorValue, ownWritableDataKeys, parseOverridesPayload, resolveChoices, sliderBounds, validateControlValue, } from "./tunableSchema.js";
+export { CONTROL_SCHEMA_VERSION, OVERRIDES_FORMAT_VERSION, convertAngle, escapePathSegment, formatColor, joinTunablePath, normalizeAngle, normalizeColorValue, parseColor, parseOverridesPayload, splitTunablePath, unescapePathSegment, validateControlValue, } from "./tunableSchema.js";
 const FRAME_CAPACITY = 240;
 const RECENT_FRAMES = 60;
-const LONG_FRAME_MS = 33.4;
+export const LONG_FRAME_MS = 33.4;
 const LATENCY_CAPACITY = 120;
 const LOG_CAPACITY = 200;
 const LOG_MESSAGE_MAX = 400;
-const COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+const LONG_FRAME_CAPACITY = 40;
+const MAX_PHASES_PER_FRAME = 24;
+const MAX_LONG_FRAME_PHASES = 8;
+const PHASE_HOT_MS = 2;
 function nowMs() {
     const perf = globalThis.performance;
     return perf !== undefined ? perf.now() : Date.now();
 }
-function inferKind(initial, hasOptions) {
-    if (hasOptions)
-        return "select";
-    if (typeof initial === "number")
-        return "slider";
-    if (typeof initial === "boolean")
-        return "toggle";
-    if (typeof initial === "string" && COLOR_PATTERN.test(initial))
-        return "color";
-    return "text";
-}
-function sliderBounds(initial, options) {
-    const min = options?.min ?? (initial < 0 ? initial * 2 : 0);
-    const max = options?.max ?? (initial > 0 ? initial * 2 : initial < 0 ? 0 : 1);
-    const step = options?.step ?? (max - min) / 100;
-    return { min, max, step };
-}
 function formatLogArg(arg) {
     if (typeof arg === "string")
         return arg;
@@ -49,45 +37,148 @@ function percentile(sorted, fraction) {
     const index = Math.min(sorted.length - 1, Math.floor(sorted.length * fraction));
     return sorted[index];
 }
-const MAX_TABLE_ENTRIES = 64;
-function discoverableKind(value) {
-    if (typeof value === "number" && Number.isFinite(value))
-        return "slider";
-    if (typeof value === "boolean")
-        return "toggle";
-    if (typeof value === "string" && COLOR_PATTERN.test(value))
-        return "color";
-    return null;
+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)`,
+    };
 }
-function discoverableEntries(candidate) {
-    if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate))
-        return [];
-    const proto = Object.getPrototypeOf(candidate);
-    if (proto !== Object.prototype && proto !== null)
-        return [];
-    const entries = [];
-    for (const [key, value] of Object.entries(candidate)) {
-        const kind = discoverableKind(value);
-        if (kind !== null)
-            entries.push([key, kind]);
-        if (entries.length > MAX_TABLE_ENTRIES)
-            return [];
+function collectScanTargets(root, meta) {
+    const skipped = [];
+    if (!isScannableContainer(root)) {
+        if (root !== null && typeof root === "object") {
+            skipped.push({ path: "", reason: "not a plain object or array" });
+        }
+        return { targets: [], skipped };
+    }
+    const out = [];
+    const visited = new Set([root]);
+    let frontier = [{ path: "", target: root }];
+    for (let depth = 0; depth <= MAX_SCAN_DEPTH && frontier.length > 0; depth += 1) {
+        const next = [];
+        for (const { path, target } of frontier) {
+            const keys = ownWritableDataKeys(target);
+            let scalarCount = 0;
+            for (const key of keys) {
+                const value = target[key];
+                const childPath = joinTunablePath(path, key);
+                const fieldMeta = meta?.[childPath];
+                const kind = discoverableKind(value, fieldMeta);
+                if (kind !== null) {
+                    scalarCount += 1;
+                    if (scalarCount > MAX_TABLE_ENTRIES) {
+                        skipped.push({ path: path === "" ? "*" : path, reason: `more than ${MAX_TABLE_ENTRIES} scalar entries` });
+                        scalarCount = -1;
+                        break;
+                    }
+                }
+            }
+            if (scalarCount < 0)
+                continue;
+            for (const key of keys) {
+                const value = target[key];
+                const childPath = joinTunablePath(path, key);
+                const fieldMeta = meta?.[childPath];
+                const kind = discoverableKind(value, fieldMeta);
+                if (kind !== null) {
+                    if (out.length >= MAX_SCAN_TARGETS) {
+                        skipped.push({ path: childPath, reason: `scan cap ${MAX_SCAN_TARGETS}` });
+                        return { targets: out, skipped };
+                    }
+                    out.push({ path: childPath, target, key, kind, options: fieldMeta });
+                    continue;
+                }
+                if (value !== null && typeof value === "object") {
+                    if (!isScannableContainer(value)) {
+                        skipped.push({ path: childPath, reason: "unsupported structure" });
+                        continue;
+                    }
+                    if (visited.has(value)) {
+                        skipped.push({ path: childPath, reason: "cycle" });
+                        continue;
+                    }
+                    if (depth === MAX_SCAN_DEPTH) {
+                        skipped.push({ path: childPath, reason: `depth > ${MAX_SCAN_DEPTH}` });
+                        continue;
+                    }
+                    visited.add(value);
+                    next.push({ path: childPath, target: value });
+                }
+            }
+        }
+        frontier = next;
     }
-    return entries;
+    return { targets: out, skipped };
 }
 export function createDevtools() {
     const signal = createChangeSignal();
     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 logEntries = [];
     let consoleCaptured = false;
     const latencySamples = [];
+    const longFrameEvents = [];
+    const phaseAccumulators = new Map();
+    let currentPhases = {};
+    let currentPhaseCount = 0;
     const controlRecords = new Map();
     const discoveredRecords = new Map();
     const probeReaders = new Map();
+    let boundProps = new WeakMap();
+    let discoverySkips = [];
     const readProbes = () => {
         const values = {};
         for (const [name, read] of probeReaders) {
@@ -105,32 +196,124 @@ export function createDevtools() {
         if (logEntries.length > LOG_CAPACITY)
             logEntries.splice(0, logEntries.length - LOG_CAPACITY);
     };
+    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: sims.reduce((sum, ms) => sum + ms, 0) / sims.length,
+            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();
+    };
     const latencyStats = () => {
         if (latencySamples.length === 0)
             return null;
@@ -150,6 +333,18 @@ export function createDevtools() {
             samples: latencySamples.length,
         };
     };
+    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,
@@ -159,33 +354,96 @@ export function createDevtools() {
         min: record.min,
         max: record.max,
         step: record.step,
-        options: record.options,
+        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, record.initial),
+        reset: () => {
+            writeControl(record, cloneValue(record.initial));
+        },
     });
     const writeControl = (record, raw) => {
-        let next = raw;
-        if (record.kind === "slider" && typeof next === "number") {
-            if (record.min !== undefined)
-                next = Math.max(record.min, next);
-            if (record.max !== undefined)
-                next = Math.min(record.max, next);
+        const validated = validateControlValue(record.kind, raw, validationContext(record));
+        if (!validated.ok)
+            return false;
+        const next = validated.value;
+        if (record.kind === "vec2" || record.kind === "vec3" || record.kind === "vec4" || record.kind === "interval") {
+            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;
         }
-        if (Object.is(record.value, next))
-            return;
-        record.value = next;
         for (const listener of record.listeners)
-            listener(next);
+            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?.options !== undefined);
+        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 bounds = kind === "slider" ? sliderBounds(initial, options) : undefined;
         const record = existing !== undefined && existing.kind === kind
             ? existing
             : {
@@ -193,17 +451,17 @@ export function createDevtools() {
                 kind,
                 label: "",
                 group: "",
-                initial,
-                value: initial,
+                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;
-        record.initial = initial;
-        record.min = bounds?.min;
-        record.max = bounds?.max;
-        record.step = bounds?.step;
-        record.options = options?.options;
+        hydrateRecord(record, initial, options, kind);
         if (options?.onChange !== undefined)
             record.listeners.add(options.onChange);
         controlRecords.set(name, record);
@@ -211,19 +469,21 @@ export function createDevtools() {
         return {
             name,
             kind,
-            initial,
+            initial: record.initial,
             get value() {
                 return record.value;
             },
             set: (value) => writeControl(record, value),
-            reset: () => writeControl(record, record.initial),
+            reset: () => {
+                writeControl(record, cloneValue(record.initial));
+            },
             subscribe: (listener) => {
                 record.listeners.add(listener);
                 return () => record.listeners.delete(listener);
             },
         };
     };
-    const bindDiscovered = (table, key, kind, accessor, source) => {
+    const bindDiscovered = (table, key, kind, accessor, source, options) => {
         const id = `${table}/${key}`;
         const existing = discoveredRecords.get(id);
         if (existing === undefined) {
@@ -232,9 +492,10 @@ export function createDevtools() {
                 table,
                 key,
                 kind,
-                initial: accessor.initial,
+                initial: cloneValue(accessor.initial),
                 enabled: false,
                 source,
+                options,
                 get: accessor.get,
                 set: accessor.set,
             });
@@ -245,31 +506,48 @@ export function createDevtools() {
         existing.source = source;
         existing.get = accessor.get;
         existing.set = accessor.set;
+        existing.kind = kind;
+        existing.options = options ?? existing.options;
         const control = controlRecords.get(id);
         if (existing.enabled && control !== undefined)
-            accessor.set(control.value);
+            accessor.set(cloneValue(control.value));
         return true;
     };
-    const scanTable = (table, candidate) => {
-        const entries = discoverableEntries(candidate);
-        if (entries.length === 0)
+    const scanTable = (table, candidate, meta) => {
+        const { targets, skipped } = collectScanTargets(candidate, meta);
+        discoverySkips = [
+            ...discoverySkips.filter((entry) => entry.path !== table && !entry.path.startsWith(`${table}/`)),
+            ...skipped.map((entry) => ({
+                path: entry.path === "" ? table : `${table}/${entry.path}`,
+                reason: entry.reason,
+            })),
+        ];
+        if (targets.length === 0)
             return 0;
-        const target = candidate;
         let changed = false;
-        for (const [key, kind] of entries) {
+        let bound = 0;
+        for (const { path, target, key, kind, options } of targets) {
+            const boundKeys = boundProps.get(target);
+            if (boundKeys?.has(key) === true && !discoveredRecords.has(`${table}/${path}`))
+                continue;
             const accessor = {
-                initial: target[key],
+                initial: cloneValue(target[key]),
                 get: () => target[key],
                 set: (value) => {
                     target[key] = value;
                 },
             };
-            if (bindDiscovered(table, key, kind, accessor, target))
+            if (bindDiscovered(table, path, kind, accessor, target, options))
                 changed = true;
+            bound += 1;
+            if (boundKeys === undefined)
+                boundProps.set(target, new Set([key]));
+            else
+                boundKeys.add(key);
         }
         if (changed)
             signal.notify();
-        return entries.length;
+        return bound;
     };
     const enableDiscovered = (id) => {
         const record = discoveredRecords.get(id);
@@ -277,20 +555,42 @@ export function createDevtools() {
             return;
         record.enabled = true;
         const current = record.get();
-        const handle = register(id, record.initial, { group: record.table, label: record.key });
-        handle.subscribe((value) => record.set(value));
-        if (!Object.is(current, record.initial))
+        const handle = register(id, record.initial, {
+            ...(record.options ?? {}),
+            group: record.options?.group ?? record.table,
+            label: record.options?.label ?? record.key,
+            kind: record.kind,
+        });
+        handle.subscribe((value) => record.set(cloneValue(value)));
+        if (JSON.stringify(current) !== JSON.stringify(record.initial))
             handle.set(current);
     };
     return {
         frame: {
-            record({ frameMs, simMs }) {
-                frameMsBuffer[frameIndex] = frameMs;
-                simMsBuffer[frameIndex] = simMs;
-                frameIndex = (frameIndex + 1) % FRAME_CAPACITY;
-                frameCount += 1;
-            },
+            record: recordFrame,
             stats: frameStats,
+            longFrames: () => longFrameEvents,
+            clearLongFrames() {
+                longFrameEvents.length = 0;
+            },
+        },
+        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) {
@@ -343,22 +643,22 @@ export function createDevtools() {
             },
             resetAll() {
                 for (const record of controlRecords.values())
-                    writeControl(record, record.initial);
+                    writeControl(record, cloneValue(record.initial));
             },
         },
         discover: {
-            bind(table, key, accessor) {
-                const kind = discoverableKind(accessor.initial);
+            bind(table, key, accessor, options) {
+                const kind = discoverableKind(accessor.initial, options);
                 if (kind === null)
                     return;
-                if (bindDiscovered(table, key, kind, accessor, null))
+                if (bindDiscovered(table, key, kind, accessor, null, options))
                     signal.notify();
             },
             scanTable,
-            scanModule(exports) {
+            scanModule(exports, meta) {
                 let total = 0;
                 for (const [name, value] of Object.entries(exports)) {
-                    total += scanTable(name, value);
+                    total += scanTable(name, value, meta);
                 }
                 return total;
             },
@@ -371,6 +671,7 @@ export function createDevtools() {
                 enabled: record.enabled,
                 read: () => record.get(),
             })),
+            skipped: () => discoverySkips,
             enable(id) {
                 enableDiscovered(id);
                 signal.notify();
@@ -380,18 +681,20 @@ export function createDevtools() {
                 if (record === undefined || !record.enabled)
                     return;
                 record.enabled = false;
-                record.set(record.initial);
+                record.set(cloneValue(record.initial));
                 controlRecords.delete(id);
                 signal.notify();
             },
             clear() {
                 for (const record of discoveredRecords.values()) {
                     if (record.enabled) {
-                        record.set(record.initial);
+                        record.set(cloneValue(record.initial));
                         controlRecords.delete(record.id);
                     }
                 }
                 discoveredRecords.clear();
+                discoverySkips = [];
+                boundProps = new WeakMap();
                 signal.notify();
             },
         },
@@ -399,21 +702,61 @@ export function createDevtools() {
             export() {
                 const enabled = [...discoveredRecords.values()].filter((r) => r.enabled).map((r) => r.id);
                 const values = {};
+                const schemas = {};
                 for (const record of controlRecords.values()) {
-                    if (!Object.is(record.value, record.initial))
-                        values[record.name] = record.value;
+                    schemas[record.name] = { kind: record.kind, schemaVersion: record.schemaVersion };
+                    const same = record.kind === "vec2" ||
+                        record.kind === "vec3" ||
+                        record.kind === "vec4" ||
+                        record.kind === "interval"
+                        ? JSON.stringify(record.value) === JSON.stringify(record.initial)
+                        : Object.is(record.value, record.initial);
+                    if (!same)
+                        values[record.name] = cloneValue(record.value);
                 }
-                return { enabled, values };
+                return {
+                    version: OVERRIDES_FORMAT_VERSION,
+                    enabled,
+                    values,
+                    schemas,
+                };
             },
-            apply(overrides) {
-                for (const id of overrides.enabled)
+            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)
-                        writeControl(record, value);
+                    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 };
             },
         },
         probes: {
@@ -434,6 +777,7 @@ export function createDevtools() {
                 frame: frameStats(),
                 render: renderSample,
                 latency: latencyStats(),
+                longFrames: [...longFrameEvents],
                 logs: [...logEntries],
                 probes: readProbes(),
                 controls: [...controlRecords.values()].map((record) => ({
@@ -448,6 +792,7 @@ export function createDevtools() {
                     value: record.get(),
                     enabled: record.enabled,
                 })),
+                skipped: [...discoverySkips],
             };
         },
     };
@@ -459,6 +804,9 @@ export function tunable(name, initial, options) {
 export function snapshotDevtools() {
     return devtools.snapshot();
 }
+export function measureProfile(name, fn) {
+    return devtools.profile.measure(name, fn);
+}
 export function instrumentLatency(target, methods, record = devtools.latency.record) {
     const wrapped = { ...target };
     for (const method of methods) {