@jgengine/core 0.10.0 → 0.12.0

package/dist/devtools/discover.d.ts

@@ -0,0 +1,32 @@
+import type { ChangeSignal } from "../store/changeSignal.js";
+import { type DevtoolsControlKind, type DiscoverySkip, type TunableOptions } from "./tunableSchema.js";
+import type { ControlRecord } from "./controls.js";
+import type { Devtools, Tunable } from "./types.js";
+/** Internal record for an auto-discovered field: identity, kind, initial value, source object, and get/set accessors. */
+export interface DiscoveredRecord {
+    id: string;
+    table: string;
+    key: string;
+    kind: DevtoolsControlKind;
+    initial: unknown;
+    enabled: boolean;
+    source: object | null;
+    options?: TunableOptions;
+    get(): unknown;
+    set(value: unknown): void;
+}
+/** Discovery subsystem: the public discover and probes facades plus internal record map and helpers. */
+export interface DiscoverModule {
+    discover: Devtools["discover"];
+    probes: Devtools["probes"];
+    readProbes: () => Record<string, unknown>;
+    enableDiscovered: (id: string) => void;
+    discoveredRecords: Map<string, DiscoveredRecord>;
+    getDiscoverySkips: () => readonly DiscoverySkip[];
+}
+/** Create the discovery subsystem that scans objects/tables for tunable fields and binds them as controls and probes. */
+export declare const createDiscoverModule: (deps: {
+    signal: ChangeSignal;
+    register: <T>(name: string, initial: T, options?: TunableOptions<T>) => Tunable<T>;
+    controlRecords: Map<string, ControlRecord>;
+}) => DiscoverModule;

package/dist/devtools/discover.js

@@ -0,0 +1,240 @@
+import { MAX_SCAN_DEPTH, MAX_SCAN_TARGETS, MAX_TABLE_ENTRIES, cloneValue, discoverableKind, isScannableContainer, joinTunablePath, ownWritableDataKeys, } from "./tunableSchema.js";
+import { formatLogArg } from "./logs.js";
+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 { targets: out, skipped };
+}
+/** Create the discovery subsystem that scans objects/tables for tunable fields and binds them as controls and probes. */
+export const createDiscoverModule = (deps) => {
+    const { signal, register, controlRecords } = deps;
+    const discoveredRecords = new Map();
+    const probeReaders = new Map();
+    let boundProps = new WeakMap();
+    let discoverySkips = [];
+    const readProbes = () => {
+        const values = {};
+        for (const [name, read] of probeReaders) {
+            try {
+                values[name] = read();
+            }
+            catch (error) {
+                values[name] = `probe failed: ${formatLogArg(error)}`;
+            }
+        }
+        return values;
+    };
+    const bindDiscovered = (table, key, kind, accessor, source, options) => {
+        const id = `${table}/${key}`;
+        const existing = discoveredRecords.get(id);
+        if (existing === undefined) {
+            discoveredRecords.set(id, {
+                id,
+                table,
+                key,
+                kind,
+                initial: cloneValue(accessor.initial),
+                enabled: false,
+                source,
+                options,
+                get: accessor.get,
+                set: accessor.set,
+            });
+            return true;
+        }
+        if (source !== null && existing.source === source)
+            return false;
+        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(cloneValue(control.value));
+        return true;
+    };
+    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;
+        let changed = false;
+        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: cloneValue(target[key]),
+                get: () => target[key],
+                set: (value) => {
+                    target[key] = value;
+                },
+            };
+            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 bound;
+    };
+    const enableDiscovered = (id) => {
+        const record = discoveredRecords.get(id);
+        if (record === undefined || record.enabled)
+            return;
+        record.enabled = true;
+        const current = record.get();
+        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 {
+        discover: {
+            bind(table, key, accessor, options) {
+                const kind = discoverableKind(accessor.initial, options);
+                if (kind === null)
+                    return;
+                if (bindDiscovered(table, key, kind, accessor, null, options))
+                    signal.notify();
+            },
+            scanTable,
+            scanModule(exports, meta) {
+                let total = 0;
+                for (const [name, value] of Object.entries(exports)) {
+                    total += scanTable(name, value, meta);
+                }
+                return total;
+            },
+            list: () => [...discoveredRecords.values()].map((record) => ({
+                id: record.id,
+                table: record.table,
+                key: record.key,
+                kind: record.kind,
+                initial: record.initial,
+                enabled: record.enabled,
+                read: () => record.get(),
+            })),
+            skipped: () => discoverySkips,
+            enable(id) {
+                enableDiscovered(id);
+                signal.notify();
+            },
+            disable(id) {
+                const record = discoveredRecords.get(id);
+                if (record === undefined || !record.enabled)
+                    return;
+                record.enabled = false;
+                record.set(cloneValue(record.initial));
+                controlRecords.delete(id);
+                signal.notify();
+            },
+            clear() {
+                for (const record of discoveredRecords.values()) {
+                    if (record.enabled) {
+                        record.set(cloneValue(record.initial));
+                        controlRecords.delete(record.id);
+                    }
+                }
+                discoveredRecords.clear();
+                discoverySkips = [];
+                boundProps = new WeakMap();
+                signal.notify();
+            },
+        },
+        probes: {
+            register(name, read) {
+                probeReaders.set(name, read);
+                signal.notify();
+                return () => {
+                    probeReaders.delete(name);
+                    signal.notify();
+                };
+            },
+            read: readProbes,
+        },
+        readProbes,
+        enableDiscovered,
+        discoveredRecords,
+        getDiscoverySkips: () => discoverySkips,
+    };
+};

package/dist/devtools/fallbackSeams.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Render seams that can resolve to a placeholder FALLBACK instead of authored content:
+ * `ground` (default green terrain), `entity`/`object` (primitive capsule/box actors),
+ * `scatter` (stylized proxy foliage).
+ */
+export type FallbackSeam = "ground" | "entity" | "object" | "scatter";
+/**
+ * Why a seam fell back: `omittedMapping` (no mapping supplied — often intended),
+ * `unpulledPack` (a mapping was supplied but its asset pack is not pulled/indexed),
+ * `noScene` (nothing authored — e.g. no environment component).
+ */
+export type FallbackCause = "omittedMapping" | "unpulledPack" | "noScene";
+/** A per-seam, per-cause count table. Serializable, allocation-stable (keys never change). */
+export type FallbackSeamCounts = Record<FallbackSeam, Record<FallbackCause, number>>;
+/** Non-zero-only view of {@link FallbackSeamCounts} returned by {@link fallbackSeamsSnapshot}. */
+export type FallbackSeamsReport = Partial<Record<FallbackSeam, Partial<Record<FallbackCause, number>>>>;
+/**
+ * Arm or disarm the fallback-seam diagnostic. Off by default; the shell arms it only when devtools
+ * is enabled (dev builds), so production is a pure no-op. Toggling clears all counts so a fresh
+ * observation starts empty and the opt-out path reports nothing.
+ * @capability render-fallback-diagnostics Enable/disable the dev-only placeholder-fallback probe.
+ */
+export declare function armFallbackSeams(on: boolean): void;
+/**
+ * Record that a render seam CHOSE a placeholder fallback (called at the choice site). A pure,
+ * allocation-free no-op when disarmed — the disarmed guard returns before touching any table.
+ *
+ * Frame-boundary model: rather than a per-frame reset (which would flicker to empty on the many
+ * frames with no React re-render), each producing seam calls {@link beginFallbackSeam} at the top of
+ * its own render/compute, then reports during that same synchronous pass. This is idempotent under
+ * React StrictMode / concurrent double-render and keeps seams that re-render independently (entities
+ * vs. scatter vs. ground) from clobbering one another. {@link endFallbackPass} only emits the log.
+ * @capability render-fallback-diagnostics Report a seam resolving to a placeholder fallback.
+ */
+export declare function reportFallbackSeam(seam: FallbackSeam, cause: FallbackCause): void;
+/** Zero one seam's tally before it re-reports (per-seam frame boundary). No-op when disarmed. */
+export declare function beginFallbackSeam(seam: FallbackSeam): void;
+/** Zero every seam's tally. Used to bracket a whole observation batch (e.g. in tests). No-op when disarmed. */
+export declare function beginFallbackPass(): void;
+/**
+ * Close an observation pass: when the set of active fallbacks changes to a non-empty signature, emit
+ * ONE deduped warn line (never per-frame — the signature dedup suppresses repeats). No-op when disarmed.
+ */
+export declare function endFallbackPass(): void;
+/**
+ * Snapshot the current fallback tally as a compact, serializable object (non-zero entries only; empty
+ * when nothing fell back). Flows into the devtools `fallbacks` probe and the `debug_snapshot` RPC.
+ * @capability render-fallback-diagnostics Read authored-vs-placeholder fallback counts per seam.
+ */
+export declare function fallbackSeamsSnapshot(): FallbackSeamsReport;

package/dist/devtools/fallbackSeams.js

@@ -0,0 +1,111 @@
+import { devtools } from "./devtools.js";
+const SEAMS = ["ground", "entity", "object", "scatter"];
+const CAUSES = ["omittedMapping", "unpulledPack", "noScene"];
+function freshCounts() {
+    const out = {};
+    for (const seam of SEAMS) {
+        const row = {};
+        for (const cause of CAUSES)
+            row[cause] = 0;
+        out[seam] = row;
+    }
+    return out;
+}
+// Module-private state. `counts` is the authoritative live tally; report sites write into it directly
+// and each re-zeros its own seam before re-tallying (see the frame-boundary note in reportFallbackSeam).
+// Pre-allocated tables so the report/begin/end hot paths do zero allocation.
+let enabled = false;
+const counts = freshCounts();
+let lastSignature = "";
+function zeroSeam(seam) {
+    const row = counts[seam];
+    for (const cause of CAUSES)
+        row[cause] = 0;
+}
+/**
+ * Arm or disarm the fallback-seam diagnostic. Off by default; the shell arms it only when devtools
+ * is enabled (dev builds), so production is a pure no-op. Toggling clears all counts so a fresh
+ * observation starts empty and the opt-out path reports nothing.
+ * @capability render-fallback-diagnostics Enable/disable the dev-only placeholder-fallback probe.
+ */
+export function armFallbackSeams(on) {
+    enabled = on;
+    for (const seam of SEAMS)
+        zeroSeam(seam);
+    lastSignature = "";
+}
+/**
+ * Record that a render seam CHOSE a placeholder fallback (called at the choice site). A pure,
+ * allocation-free no-op when disarmed — the disarmed guard returns before touching any table.
+ *
+ * Frame-boundary model: rather than a per-frame reset (which would flicker to empty on the many
+ * frames with no React re-render), each producing seam calls {@link beginFallbackSeam} at the top of
+ * its own render/compute, then reports during that same synchronous pass. This is idempotent under
+ * React StrictMode / concurrent double-render and keeps seams that re-render independently (entities
+ * vs. scatter vs. ground) from clobbering one another. {@link endFallbackPass} only emits the log.
+ * @capability render-fallback-diagnostics Report a seam resolving to a placeholder fallback.
+ */
+export function reportFallbackSeam(seam, cause) {
+    if (!enabled)
+        return;
+    counts[seam][cause] += 1;
+}
+/** Zero one seam's tally before it re-reports (per-seam frame boundary). No-op when disarmed. */
+export function beginFallbackSeam(seam) {
+    if (!enabled)
+        return;
+    zeroSeam(seam);
+}
+/** Zero every seam's tally. Used to bracket a whole observation batch (e.g. in tests). No-op when disarmed. */
+export function beginFallbackPass() {
+    if (!enabled)
+        return;
+    for (const seam of SEAMS)
+        zeroSeam(seam);
+}
+function signature() {
+    let sig = "";
+    for (const seam of SEAMS) {
+        for (const cause of CAUSES) {
+            const n = counts[seam][cause];
+            if (n > 0)
+                sig += `${seam}:${cause}=${n}|`;
+        }
+    }
+    return sig;
+}
+/**
+ * Close an observation pass: when the set of active fallbacks changes to a non-empty signature, emit
+ * ONE deduped warn line (never per-frame — the signature dedup suppresses repeats). No-op when disarmed.
+ */
+export function endFallbackPass() {
+    if (!enabled)
+        return;
+    const sig = signature();
+    if (sig === lastSignature)
+        return;
+    lastSignature = sig;
+    if (sig === "")
+        return;
+    devtools.logs.push("warn", `[jgengine] render seams resolved to placeholder fallbacks — ${sig.replace(/\|$/, "").replaceAll("|", ", ")}. ` +
+        `Author the missing mapping/pack/scene, or ignore if the placeholder is intended.`);
+}
+/**
+ * Snapshot the current fallback tally as a compact, serializable object (non-zero entries only; empty
+ * when nothing fell back). Flows into the devtools `fallbacks` probe and the `debug_snapshot` RPC.
+ * @capability render-fallback-diagnostics Read authored-vs-placeholder fallback counts per seam.
+ */
+export function fallbackSeamsSnapshot() {
+    const out = {};
+    for (const seam of SEAMS) {
+        let row;
+        for (const cause of CAUSES) {
+            const n = counts[seam][cause];
+            if (n > 0)
+                (row ??= {})[cause] = n;
+        }
+        if (row !== undefined)
+            out[seam] = row;
+    }
+    return out;
+}

package/dist/devtools/frame.d.ts

@@ -0,0 +1,15 @@
+import type { Devtools } from "./types.js";
+/** Frame duration in milliseconds above which a frame is recorded as a long-frame spike (~30fps budget). */
+export declare const LONG_FRAME_MS = 33.4;
+/** @internal */
+export declare function nowMs(): number;
+/** Frame subsystem exposing the frame-timing, profiling, and render-sample facades. */
+export interface FrameModule {
+    frame: Devtools["frame"];
+    profile: Devtools["profile"];
+    render: Devtools["render"];
+}
+/** Create the frame subsystem that records frame/sim/phase timings, computes stats, and captures long-frame events. */
+export declare const createFrameModule: (deps: {
+    readProbes: () => Record<string, unknown>;
+}) => FrameModule;