@vgai/engine 0.5.11 → 0.5.13

package/dist/data/curve.js

@@ -0,0 +1,230 @@
+/**
+ * Curve FIELDS in data assets — a response curve a designer shapes, living
+ * inside an ordinary `.data.json` like any other tunable value.
+ *
+ * A curve is a FIELD TYPE, never a file type: there is no `.curve.json`, no
+ * curve asset class, no baked LUT, and no document. `curve(axes)` is a real
+ * Zod schema you drop into a `*.schema.ts` beside `z.number()`, so the value
+ * lives in the same data file, hot-swaps through the same `defineData` handle,
+ * and is edited by the same Data panel that edits everything else.
+ *
+ * The JSON a designer (or an agent) reads and writes:
+ *
+ * ```json
+ * { "interpolation": "smooth",
+ *   "points": [{ "x": 0, "y": 1 }, { "x": 12, "y": 0.85 }, { "x": 30, "y": 0.2 }] }
+ * ```
+ *
+ * TWO MODES, NO TANGENTS. `linear` and `smooth`, and nothing else. Per-key
+ * tangent handles would double the JSON, make it unreadable to an agent, and
+ * hand every author a way to make a curve overshoot its own points. Smoothness
+ * is DERIVED instead — Fritsch–Carlson monotone cubic tangents, computed from
+ * the points themselves — so the interpolant is guaranteed to stay inside each
+ * segment's `[yLeft, yRight]` band. "Shape it by moving points" is the whole
+ * authoring model.
+ *
+ * RUNG AUDIT (recorded decision, 2026-08-14): no npm dependency. The candidate
+ * packages (`monotone-cubic-spline` and its siblings) are unmaintained
+ * micro-packages, and d3's `curveMonotoneX` is an SVG PATH GENERATOR — it
+ * draws, it does not sample `y` at an `x`. What we need is ~40 lines of
+ * well-known numerics with no API surface, so it is written here.
+ *
+ * `sampleCurve` is the entire runtime: a pure function, no class, no cache
+ * object, no "curve system". Game code calls it every frame from its own
+ * update, the same way it reads any other tuning value.
+ */
+import { z } from 'zod';
+/** How the marker rides out to the emitted JSON Schema — the editor's and the dev menu's detection key, the exact shape `dataRef` uses with `x-vgai-ref`. */
+const CURVE_META_KEY = 'x-vgai-curve';
+function axisLabel(axes, axis) {
+    return axes[axis].label ?? axis;
+}
+/** Every out-of-domain / ordering problem in one pass, as teaching issues (`parseDataJson`'s "errors teach" doctrine, §6.5). */
+function checkPoints(value, axes, ctx) {
+    const points = value.points;
+    for (let i = 0; i < points.length; i++) {
+        const point = points[i];
+        for (const axis of ['x', 'y']) {
+            const { min, max } = axes[axis];
+            if (point[axis] < min || point[axis] > max) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['points', i, axis],
+                    message: `${point[axis]} is outside this curve's ${axisLabel(axes, axis)} domain ` +
+                        `[${min}, ${max}] — move the point inside the domain, or widen the axis in the ` +
+                        `schema (curve({ ${axis}: { min, max } })).`,
+                });
+            }
+        }
+        if (i === 0)
+            continue;
+        const previous = points[i - 1];
+        if (point.x <= previous.x) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['points', i, 'x'],
+                message: `${point.x} must be strictly greater than the previous point's x (${previous.x}) — ` +
+                    'curve points run left to right along x, with no duplicate x. Sort the points, or ' +
+                    'nudge this one.',
+            });
+        }
+    }
+}
+/**
+ * A Zod schema for a data-asset FIELD holding a response curve. Use it in a
+ * `.schema.ts` exactly like any other field:
+ *
+ * ```ts
+ * export const TuningSchema = z.object({
+ *   spawnRate: z.number().min(0).max(10).default(1),
+ *   difficultyRamp: curve({
+ *     x: { min: 0, max: 300, label: 'Sim time (s)' },
+ *     y: { min: 0, max: 2, label: 'Spawn multiplier' },
+ *   }).describe('How hard the game leans on the player as the round runs.'),
+ * });
+ * ```
+ *
+ * The schema is STRICT (an unrecognized key is an error, never a silent
+ * strip), demands at least two points, and enforces strictly-increasing `x`
+ * with every point inside the declared axes — each with a message that names
+ * the fix rather than the rule.
+ *
+ * The emitted JSON Schema (`toDataJsonSchema`) carries
+ * `"x-vgai-curve": axes` — a Zod `.meta()`, which survives `z.toJSONSchema`
+ * including inside a table's `additionalProperties` row schema, exactly the
+ * way `dataRef`'s `"x-vgai-ref"` does. That marker is what makes the editor's
+ * Data panel render a curve EDITOR instead of a raw-JSON cell, with no emitter
+ * changes anywhere.
+ */
+export function curve(axes) {
+    const point = z.strictObject({
+        x: z.number().describe(`Position along ${axisLabel(axes, 'x')}.`),
+        y: z.number().describe(`Value at that position, along ${axisLabel(axes, 'y')}.`),
+    });
+    return z
+        .strictObject({
+        interpolation: z
+            .enum(['linear', 'smooth'])
+            .describe('How the value moves between points: "linear" for straight segments, ' +
+            '"smooth" for a monotone cubic that never overshoots them.'),
+        points: z
+            .array(point)
+            .min(2, {
+            message: 'a curve needs at least two points — add another { "x": …, "y": … } so the ' +
+                'value has somewhere to travel between.',
+        })
+            .describe('Keys in increasing x order; the value is clamped outside the first/last x.'),
+    })
+        .superRefine((value, ctx) => checkPoints(value, axes, ctx))
+        .meta({ [CURVE_META_KEY]: axes });
+}
+/**
+ * Read a curve field's declared axes back off a LIVE Zod schema (as opposed to
+ * the emitted JSON Schema, which the editor's Data panel reads instead).
+ *
+ * This is the dev-menu capability's detection door: it derives its rows by
+ * walking the game's own `TuningSchema` object, so it needs the axes from the
+ * schema in hand. Wrappers (`.optional()`, `.default(…)`, `.describe(…)` chains
+ * that re-wrap) hide the metadata behind an inner type, so a bounded unwrap
+ * walks down to it.
+ */
+export function curveAxesOf(schema) {
+    let current = schema;
+    for (let depth = 0; depth < 5 && current; depth++) {
+        const meta = current.meta?.();
+        const axes = meta?.[CURVE_META_KEY];
+        if (axes && typeof axes === 'object' && 'x' in axes && 'y' in axes)
+            return axes;
+        current = current.def?.innerType;
+    }
+    return undefined;
+}
+/**
+ * Fritsch–Carlson tangents: the ordinary cubic-Hermite slopes, then limited so
+ * the interpolant cannot overshoot the data. This is what makes "smooth" safe
+ * to hand a designer — a curve that dips below its own points would silently
+ * feed the game a value nobody authored.
+ */
+function monotoneTangents(points) {
+    const n = points.length;
+    const secants = [];
+    for (let i = 0; i < n - 1; i++) {
+        const left = points[i];
+        const right = points[i + 1];
+        secants.push((right.y - left.y) / (right.x - left.x));
+    }
+    const tangents = [secants[0]];
+    for (let i = 1; i < n - 1; i++) {
+        tangents.push((secants[i - 1] + secants[i]) / 2);
+    }
+    tangents.push(secants[n - 2]);
+    for (let i = 0; i < n - 1; i++) {
+        const secant = secants[i];
+        if (secant === 0) {
+            // A flat segment must stay flat: any slope at either end would bulge.
+            tangents[i] = 0;
+            tangents[i + 1] = 0;
+            continue;
+        }
+        let alpha = tangents[i] / secant;
+        let beta = tangents[i + 1] / secant;
+        // A tangent fighting the segment's own direction is a local extremum the
+        // data does not have.
+        if (alpha < 0) {
+            tangents[i] = 0;
+            alpha = 0;
+        }
+        if (beta < 0) {
+            tangents[i + 1] = 0;
+            beta = 0;
+        }
+        const radius = alpha * alpha + beta * beta;
+        if (radius > 9) {
+            const scale = 3 / Math.sqrt(radius);
+            tangents[i] = scale * alpha * secant;
+            tangents[i + 1] = scale * beta * secant;
+        }
+    }
+    return tangents;
+}
+/**
+ * The curve's value at `x` — the whole runtime API.
+ *
+ * Read it every frame from the game's own update, the way every other data
+ * value is read (`tuning.get()` then sample); never precompute a table, and
+ * never hold the result across frames — an edit to the `.data.json` hot-swaps
+ * underneath you and that is the point.
+ *
+ * Outside `[first.x, last.x]` the value CLAMPS to the nearest endpoint: a
+ * curve declares what it knows about, and extrapolating past it would invent
+ * numbers nobody authored.
+ */
+export function sampleCurve(value, x) {
+    const points = value.points;
+    if (points.length === 0)
+        return 0;
+    const first = points[0];
+    const last = points[points.length - 1];
+    if (points.length === 1 || x <= first.x)
+        return first.y;
+    if (x >= last.x)
+        return last.y;
+    let i = 0;
+    while (i < points.length - 2 && x >= points[i + 1].x)
+        i++;
+    const left = points[i];
+    const right = points[i + 1];
+    const span = right.x - left.x;
+    if (span <= 0)
+        return left.y; // duplicate x — the schema rejects it; a hand-built value might not
+    const t = (x - left.x) / span;
+    if (value.interpolation === 'linear')
+        return left.y + (right.y - left.y) * t;
+    const tangents = monotoneTangents(points);
+    const t2 = t * t;
+    const t3 = t2 * t;
+    return ((2 * t3 - 3 * t2 + 1) * left.y +
+        (t3 - 2 * t2 + t) * span * tangents[i] +
+        (-2 * t3 + 3 * t2) * right.y +
+        (t3 - t2) * span * tangents[i + 1]);
+}

package/dist/data/vite-plugin-data.d.ts

@@ -54,10 +54,10 @@ export interface VgaiDataCheckOptions {
  * The fs half of checks 1 + 2, extracted from the plugin hook so it is
  * directly unit-testable against a fixture folder (no rollup context needed).
  */
-export declare function collectDataCheckProblems(options: VgaiDataCheckOptions): {
+export declare function collectDataCheckProblems(options: VgaiDataCheckOptions): Promise<{
     errors: string[];
     warnings: string[];
-};
+}>;
 /** True iff a bundled module id is tool code that must never ship (§4). Pure, unit-tested. */
 export declare function isToolModuleId(id: string): boolean;
 /**

package/dist/data/vite-plugin-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite-plugin-data.d.ts","sourceRoot":"","sources":["../../src/data/vite-plugin-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQ7B,4GAA4G;AAC5G,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,mGAAmG;IACnG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAuGD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,oBAAoB,GAAG;IACvE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CA2DA;AAED,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAGlD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAmCnE"}
+{"version":3,"file":"vite-plugin-data.d.ts","sourceRoot":"","sources":["../../src/data/vite-plugin-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAUH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQ7B,4GAA4G;AAC5G,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,mGAAmG;IACnG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AA4HD;;;GAGG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC;IACrF,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC,CAkED;AAED,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAGlD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAmCnE"}

package/dist/data/vite-plugin-data.js

@@ -37,24 +37,32 @@
  * and runtime parse-on-load, but no build-time schema check — the warning
  * names the registry file to fix.
  */
-import { readdirSync, readFileSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
 import { parseDataJson, toDataJsonSchema } from './data-asset';
 import { collectDeclaredRefFields, findDanglingDataRefs, findMissingRefTargets, } from './data-check-core';
+async function loadNodeIo() {
+    const [fs, path] = await Promise.all([import('node:fs'), import('node:path')]);
+    return {
+        readdirSync: fs.readdirSync,
+        readFileSync: fs.readFileSync,
+        statSync: fs.statSync,
+        join: path.join,
+        relative: path.relative,
+    };
+}
 /** Recursively collect `*.data.json` under `dir` (absent dir → empty — a project with no data assets builds fine). */
-function findDataFiles(dir) {
+function findDataFiles(io, dir) {
     let entries;
     try {
-        entries = readdirSync(dir);
+        entries = io.readdirSync(dir);
     }
     catch {
         return [];
     }
     const out = [];
     for (const entry of entries) {
-        const full = join(dir, entry);
-        if (statSync(full).isDirectory())
-            out.push(...findDataFiles(full));
+        const full = io.join(dir, entry);
+        if (io.statSync(full).isDirectory())
+            out.push(...findDataFiles(io, full));
         else if (entry.endsWith('.data.json'))
             out.push(full);
     }
@@ -68,11 +76,11 @@ function assetStem(sourcePath) {
         .pop()
         ?.replace(/\.data\.json$/, '') ?? rel);
 }
-function parseAllDataFiles(root, registered, errors, warnings) {
+function parseAllDataFiles(io, root, registered, errors, warnings) {
     const parsedByStem = new Map();
     const pathsByStem = new Map();
-    for (const abs of findDataFiles(join(root, 'src', 'data'))) {
-        const rel = relative(root, abs).split('\\').join('/');
+    for (const abs of findDataFiles(io, io.join(root, 'src', 'data'))) {
+        const rel = io.relative(root, abs).split('\\').join('/');
         const stem = assetStem(rel);
         const paths = pathsByStem.get(stem);
         if (paths)
@@ -80,7 +88,7 @@ function parseAllDataFiles(root, registered, errors, warnings) {
         else
             pathsByStem.set(stem, [rel]);
         try {
-            parsedByStem.set(stem, JSON.parse(readFileSync(abs, 'utf-8')));
+            parsedByStem.set(stem, JSON.parse(io.readFileSync(abs, 'utf-8')));
         }
         catch (err) {
             errors.push(`"${rel}" is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
@@ -109,12 +117,13 @@ function parseAllDataFiles(root, registered, errors, warnings) {
  * The fs half of checks 1 + 2, extracted from the plugin hook so it is
  * directly unit-testable against a fixture folder (no rollup context needed).
  */
-export function collectDataCheckProblems(options) {
+export async function collectDataCheckProblems(options) {
+    const io = await loadNodeIo();
     const root = options.root ?? process.cwd();
     const errors = [];
     const warnings = [];
     const registered = new Set(options.assets.map((a) => a.sourcePath.split('\\').join('/')));
-    const { parsedByStem, ambiguousStems } = parseAllDataFiles(root, registered, errors, warnings);
+    const { parsedByStem, ambiguousStems } = parseAllDataFiles(io, root, registered, errors, warnings);
     // Check 1 — registered assets validate through the exact runtime parse.
     for (const asset of options.assets) {
         const rel = asset.sourcePath.split('\\').join('/');
@@ -184,8 +193,8 @@ export function vgaiDataCheck(options) {
     return {
         name: 'vgai:data-check',
         apply: 'build',
-        buildStart() {
-            const { errors, warnings } = collectDataCheckProblems(options);
+        async buildStart() {
+            const { errors, warnings } = await collectDataCheckProblems(options);
             for (const warning of warnings)
                 this.warn(warning);
             if (errors.length > 0) {

package/dist/dev/performance-profiler.d.ts

@@ -85,6 +85,7 @@ export interface PerformanceSnapshot {
 /** Game-owned, bounded external store for browser-native performance diagnostics. */
 export declare function createPerformanceProfiler(initiallyEnabled?: boolean): {
     enabled: boolean;
+    telemetryEnabled: boolean;
     readonly recording: boolean;
     startRecording(): void;
     stopRecording(): void;

package/dist/dev/performance-profiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"performance-profiler.d.ts","sourceRoot":"","sources":["../../src/dev/performance-profiler.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,yEAAyE;AACzE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;CACzC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;CACzC;AAUD,qFAAqF;AACrF,wBAAgB,yBAAyB,CAAC,gBAAgB,UAAQ;aA8E3C,OAAO;;;;;;;mBA8CX,MAAM;;;yBAqBF,MAAM,SAAS,MAAM,QAAQ,MAAM;;;uBAiBnC,MAAM;wBAWL;QAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB;2DACmD;QACnD,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB;;wBAqCmB,MAAM,IAAI;;;EAejC;AAED,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,yBAAyB,CAAC,CAAC"}
+{"version":3,"file":"performance-profiler.d.ts","sourceRoot":"","sources":["../../src/dev/performance-profiler.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,yEAAyE;AACzE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;CACzC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;CACzC;AAUD,qFAAqF;AACrF,wBAAgB,yBAAyB,CAAC,gBAAgB,UAAQ;aAoF3C,OAAO;sBASE,OAAO;;;;;;;mBAkDpB,MAAM;;;yBAqBF,MAAM,SAAS,MAAM,QAAQ,MAAM;;;uBAiBnC,MAAM;wBAWL;QAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB;2DACmD;QACnD,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB;;wBAqCmB,MAAM,IAAI;;;EAejC;AAED,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/dev/performance-profiler.js

@@ -19,6 +19,12 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
     let frameSystems = [];
     let frameComponents = [];
     let enabled = initiallyEnabled;
+    // The header's always-visible FPS sparkline needs frame INTERVALS without
+    // turning on the full profiler. Full profiling measures phases/systems,
+    // issues GPU timer queries at render sites, and intentionally warns about
+    // overhead; a glanceable heartbeat must not silently opt the user into all
+    // of that work. `telemetryEnabled` records only the frame envelope.
+    let telemetryEnabled = false;
     let recording = false;
     let frameId = 0;
     let frameStart = 0;
@@ -87,13 +93,30 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
             if (enabled === value)
                 return;
             enabled = value;
+            if (value && !telemetryEnabled)
+                lastFrameStart = 0;
+            publish();
+        },
+        get telemetryEnabled() {
+            return telemetryEnabled;
+        },
+        set telemetryEnabled(value) {
+            if (telemetryEnabled === value)
+                return;
+            const wasInactive = !enabled && !telemetryEnabled;
+            telemetryEnabled = value;
+            if (value && wasInactive)
+                lastFrameStart = 0;
             publish();
         },
         get recording() {
             return recording;
         },
         startRecording() {
+            const wasInactive = !enabled && !telemetryEnabled;
             enabled = true;
+            if (wasInactive)
+                lastFrameStart = 0;
             recording = true;
             frames.length = 0;
             publish();
@@ -107,7 +130,7 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
             publish();
         },
         beginFrame() {
-            if (!enabled)
+            if (!enabled && !telemetryEnabled)
                 return;
             currentPhases.clear();
             currentSystems.clear();
@@ -201,7 +224,7 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
             };
         },
         endFrame() {
-            if (!enabled)
+            if (!enabled && !telemetryEnabled)
                 return;
             const timestamp = now();
             const intervalMs = lastFrameStart === 0 ? 0 : frameStart - lastFrameStart;

package/dist/ecs/user-data.d.ts

@@ -76,20 +76,50 @@
  *                           implementation parts without adding wrappers.
  * - `authoringLabel`      — authored literal name (or component tag fallback)
  *                           for that source-backed component instance.
+ * - `authoringComponent`  — exact source component identity for portable-CSF
+ *                           association; unlike the label, never user-facing copy.
+ * - `authoringDocument`   — generic reference to the project-tool document
+ *                           that owns this scene instance's authored asset.
  * - `editorHelper`        — `true` for editor-only helper objects (gizmos, wireframes).
+ *
+ * Hierarchy-presentation convention (written by GAME code, read by the editor —
+ * see `../adapter/hierarchy-marks.ts`, which is the ONLY place these two are
+ * read/written from; the `vgai` prefix marks them as the HOST's namespace on a
+ * node a game owns, unlike every other key above, which the engine/editor also
+ * write):
+ * - `vgaiComponentRoot`   — display name of the component instance this subtree
+ *                           IS. The node renders as one collapsed, expandable
+ *                           row named for it.
+ * - `vgaiBuiltInternal`   — `true` on the ROOT of a subtree runtime code
+ *                           CONSTRUCTED rather than authored (skeleton bones,
+ *                           particle renderers). Subtree-scoped: everything
+ *                           below a marked node is built-internal too.
+ * - `vgaiBodyOwner`       — the rigid body that OWNS this node's pose, written
+ *                           by the code that attaches the body (see
+ *                           `../adapter/body-marks.ts`, the only reader/writer).
+ *                           A transform edit on such a node must be applied to
+ *                           the BODY, or the next physics step writes the node
+ *                           straight back.
  * - `editorHelperType`    — which kind of helper (lights/particles/pivot/navmesh/...).
  * - `editorIcon`          — `true` for editor billboard icon sprites.
  * - `skeletonVisible`     — per-entity editor preference for its bone overlay.
  * - `skeletonEnabled`     — resolved visibility preference on a skeleton helper.
  * - `envObject`           — `true` for environment objects (ambient light, etc.).
+ * - `reflectionProbe`     — live project-owned reflection probe projected from
+ *                           JSX props for renderer/editor integration.
+ * - `constraints`         — live project-owned spatial constraints projected
+ *                           into the shared Inspector and viewport.
  * - `splineControlPoint`  — index of a spline control-point drag handle.
  * - `vcDirIdx`            — view-cube face direction index (0=+X,1=-X,2=+Y,...).
  */
 import type * as THREE from 'three';
 import type { ParticleSystem } from 'three.quarks';
+import type { ConstraintMark } from '../adapter/constraint';
+import type { RapierEditableBody } from '../adapter/rapier-physics-adapter';
+import type { ReflectionProbeMark } from '../adapter/reflection-probe';
 import type { XStateAnimationBinding } from '../animation/xstate-animation-binding';
 /** The kinds of editor helper objects tagged via `editorHelperType`. */
-export type EditorHelperType = 'lights' | 'cameras' | 'audio' | 'colliders' | 'joints' | 'lod' | 'splines' | 'particles' | 'particle-shape' | 'pivot' | 'navmesh' | 'skeletons';
+export type EditorHelperType = 'lights' | 'cameras' | 'audio' | 'colliders' | 'joints' | 'lod' | 'splines' | 'particles' | 'particle-shape' | 'pivot' | 'navmesh' | 'constraints' | 'reflection-probes' | 'skeletons';
 /**
  * Maps each canonical accessor name to its value type. This is the single
  * source of truth for what every known `userData` key holds.
@@ -122,12 +152,23 @@ export interface UserDataSchema {
     authoringRoot: boolean;
     authoringInstance: string;
     authoringLabel: string;
+    vgaiComponentRoot: string;
+    vgaiBuiltInternal: boolean;
+    vgaiBodyOwner: RapierEditableBody;
+    authoringComponent: string;
+    authoringDocument: {
+        readonly kind: 'project-tool';
+        readonly name: string;
+        readonly title: string;
+    };
     editorHelper: boolean;
     editorHelperType: EditorHelperType;
     editorIcon: boolean;
     skeletonVisible: boolean;
     skeletonEnabled: boolean;
     envObject: boolean;
+    constraints: readonly ConstraintMark[];
+    reflectionProbe: ReflectionProbeMark;
     vcDirIdx: number;
     /** W1a navmesh path-probe preview polyline: the routed waypoints, mirrored
      *  onto the preview line Object3D so e2e can read the path back from the
@@ -170,12 +211,19 @@ export declare const UserDataKeys: {
     readonly authoringRoot: "authoringRoot";
     readonly authoringInstance: "authoringInstance";
     readonly authoringLabel: "authoringLabel";
+    readonly vgaiComponentRoot: "vgaiComponentRoot";
+    readonly vgaiBuiltInternal: "vgaiBuiltInternal";
+    readonly vgaiBodyOwner: "vgaiBodyOwner";
+    readonly authoringComponent: "authoringComponent";
+    readonly authoringDocument: "authoringDocument";
     readonly editorHelper: "editorHelper";
     readonly editorHelperType: "editorHelperType";
     readonly editorIcon: "editorIcon";
     readonly skeletonVisible: "skeletonVisible";
     readonly skeletonEnabled: "skeletonEnabled";
     readonly envObject: "envObject";
+    readonly constraints: "constraints";
+    readonly reflectionProbe: "reflectionProbe";
     readonly vcDirIdx: "vcDirIdx";
     readonly navPathPoints: "navPathPoints";
 };

package/dist/ecs/user-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user-data.d.ts","sourceRoot":"","sources":["../../src/ecs/user-data.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"user-data.d.ts","sourceRoot":"","sources":["../../src/ecs/user-data.ts"],"names":[],"mappings":"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"}

package/dist/ecs/user-data.js

@@ -76,12 +76,39 @@
  *                           implementation parts without adding wrappers.
  * - `authoringLabel`      — authored literal name (or component tag fallback)
  *                           for that source-backed component instance.
+ * - `authoringComponent`  — exact source component identity for portable-CSF
+ *                           association; unlike the label, never user-facing copy.
+ * - `authoringDocument`   — generic reference to the project-tool document
+ *                           that owns this scene instance's authored asset.
  * - `editorHelper`        — `true` for editor-only helper objects (gizmos, wireframes).
+ *
+ * Hierarchy-presentation convention (written by GAME code, read by the editor —
+ * see `../adapter/hierarchy-marks.ts`, which is the ONLY place these two are
+ * read/written from; the `vgai` prefix marks them as the HOST's namespace on a
+ * node a game owns, unlike every other key above, which the engine/editor also
+ * write):
+ * - `vgaiComponentRoot`   — display name of the component instance this subtree
+ *                           IS. The node renders as one collapsed, expandable
+ *                           row named for it.
+ * - `vgaiBuiltInternal`   — `true` on the ROOT of a subtree runtime code
+ *                           CONSTRUCTED rather than authored (skeleton bones,
+ *                           particle renderers). Subtree-scoped: everything
+ *                           below a marked node is built-internal too.
+ * - `vgaiBodyOwner`       — the rigid body that OWNS this node's pose, written
+ *                           by the code that attaches the body (see
+ *                           `../adapter/body-marks.ts`, the only reader/writer).
+ *                           A transform edit on such a node must be applied to
+ *                           the BODY, or the next physics step writes the node
+ *                           straight back.
  * - `editorHelperType`    — which kind of helper (lights/particles/pivot/navmesh/...).
  * - `editorIcon`          — `true` for editor billboard icon sprites.
  * - `skeletonVisible`     — per-entity editor preference for its bone overlay.
  * - `skeletonEnabled`     — resolved visibility preference on a skeleton helper.
  * - `envObject`           — `true` for environment objects (ambient light, etc.).
+ * - `reflectionProbe`     — live project-owned reflection probe projected from
+ *                           JSX props for renderer/editor integration.
+ * - `constraints`         — live project-owned spatial constraints projected
+ *                           into the shared Inspector and viewport.
  * - `splineControlPoint`  — index of a spline control-point drag handle.
  * - `vcDirIdx`            — view-cube face direction index (0=+X,1=-X,2=+Y,...).
  */
@@ -115,12 +142,19 @@ export const UserDataKeys = {
     authoringRoot: 'authoringRoot',
     authoringInstance: 'authoringInstance',
     authoringLabel: 'authoringLabel',
+    vgaiComponentRoot: 'vgaiComponentRoot',
+    vgaiBuiltInternal: 'vgaiBuiltInternal',
+    vgaiBodyOwner: 'vgaiBodyOwner',
+    authoringComponent: 'authoringComponent',
+    authoringDocument: 'authoringDocument',
     editorHelper: 'editorHelper',
     editorHelperType: 'editorHelperType',
     editorIcon: 'editorIcon',
     skeletonVisible: 'skeletonVisible',
     skeletonEnabled: 'skeletonEnabled',
     envObject: 'envObject',
+    constraints: 'constraints',
+    reflectionProbe: 'reflectionProbe',
     vcDirIdx: 'vcDirIdx',
     navPathPoints: 'navPathPoints',
 };

package/dist/index.d.ts

@@ -20,14 +20,13 @@
  *   - game setup contract: `GameContext`/`GameCleanup`/`GameSetupFn`, `fromSetup`
  *   - surface vocabulary: `AdapterSurface`
  *   - manifest-driven mount: `mountManifestRoots` + its option/result types
- *   - asset-format entry points: `parseMaterialFile` (.mat.json), `parseInstancesFile`
  *   - game manifest (vgai.project.json) entry point: `loadGameManifest`
  */
 export type { AdapterSurface } from './adapter/adapter-surface';
 export { fromSetup } from './adapter/setup-three-root-adapter';
-export { AssetParseError, parseInstancesFile, parseMaterialFile } from './asset-formats/parse';
+export { AssetParseError } from './asset-parse-error';
 export type { AdapterRoot, GameManifest, ResolvedAdapter, ResolvedAdapterRoot, ResolvedGameManifest, RootAdapter, } from './manifest';
-export { CAPABILITY_CEILINGS, DEFAULT_SERVER_MODULE, loadGameManifest } from './manifest';
+export { DEFAULT_SERVER_MODULE, loadGameManifest } from './manifest';
 export type { GameSession } from './runtime/create-runtime';
 export type { MountEntry, MountedManifestSession, MountManifestOptions, } from './runtime/mount-manifest';
 export { mountManifestRoots } from './runtime/mount-manifest';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/F,YAAY,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC1F,YAAY,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,YAAY,EACV,UAAU,EACV,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,YAAY,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACrE,YAAY,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,YAAY,EACV,UAAU,EACV,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -20,10 +20,9 @@
  *   - game setup contract: `GameContext`/`GameCleanup`/`GameSetupFn`, `fromSetup`
  *   - surface vocabulary: `AdapterSurface`
  *   - manifest-driven mount: `mountManifestRoots` + its option/result types
- *   - asset-format entry points: `parseMaterialFile` (.mat.json), `parseInstancesFile`
  *   - game manifest (vgai.project.json) entry point: `loadGameManifest`
  */
 export { fromSetup } from './adapter/setup-three-root-adapter';
-export { AssetParseError, parseInstancesFile, parseMaterialFile } from './asset-formats/parse';
-export { CAPABILITY_CEILINGS, DEFAULT_SERVER_MODULE, loadGameManifest } from './manifest';
+export { AssetParseError } from './asset-parse-error';
+export { DEFAULT_SERVER_MODULE, loadGameManifest } from './manifest';
 export { mountManifestRoots } from './runtime/mount-manifest';

package/dist/manifest/index.d.ts

@@ -1,6 +1,6 @@
 export { isManifestFilename, MANIFEST_FILENAME, REMOVED_MANIFEST_FILENAME, removedManifestFilenameMessage, } from './filename';
 export type { ResolvedAdapter, ResolvedAdapterRoot, ResolvedGameManifest } from './load';
-export { CAPABILITY_CEILINGS, DEFAULT_SERVER_MODULE, loadGameManifest } from './load';
-export type { AdapterRoot, GameManifest, IngestStrategy, RootAdapter, Tier, } from './schema';
-export { AdapterRootSchema, GameManifestSchema, IngestStrategySchema, RootAdapterSchema, TierSchema, } from './schema';
+export { DEFAULT_SERVER_MODULE, loadGameManifest } from './load';
+export type { AdapterRoot, GameManifest, RootAdapter } from './schema';
+export { AdapterRootSchema, GameManifestSchema, RootAdapterSchema } from './schema';
 //# sourceMappingURL=index.d.ts.map

package/dist/manifest/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/manifest/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AACzF,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AACtF,YAAY,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,WAAW,EACX,IAAI,GACL,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,UAAU,GACX,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/manifest/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AACzF,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AACjE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC"}