@vgai/engine 0.5.10 → 0.5.12

package/src/data/curve.ts

@@ -0,0 +1,263 @@
+/**
+ * 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';
+
+/** One authored key: a `y` value at an `x` position. No tangents — see above. */
+export interface CurvePoint {
+  x: number;
+  y: number;
+}
+
+/** A curve field's value, exactly as it sits in the `.data.json`. */
+export interface CurveValue {
+  interpolation: 'linear' | 'smooth';
+  points: CurvePoint[];
+}
+
+/**
+ * The curve's DOMAIN, declared by the engineer in the schema (never by the
+ * data): what the axes mean and how far they run. The editor draws its rails
+ * from this and clamps every drag to it; the schema rejects a point outside
+ * it.
+ */
+export interface CurveAxes {
+  x: { min: number; max: number; label?: string };
+  y: { min: number; max: number; label?: string };
+}
+
+/** 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: CurveAxes, axis: 'x' | 'y'): string {
+  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: CurveValue, axes: CurveAxes, ctx: z.RefinementCtx): void {
+  const points = value.points;
+  for (let i = 0; i < points.length; i++) {
+    const point = points[i] as CurvePoint;
+    for (const axis of ['x', 'y'] as const) {
+      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] as CurvePoint;
+    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: CurveAxes): z.ZodType<CurveValue> {
+  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 }) as unknown as z.ZodType<CurveValue>;
+}
+
+/**
+ * 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: z.ZodType): CurveAxes | undefined {
+  let current: unknown = schema;
+  for (let depth = 0; depth < 5 && current; depth++) {
+    const meta = (current as z.ZodType).meta?.() as Record<string, unknown> | undefined;
+    const axes = meta?.[CURVE_META_KEY];
+    if (axes && typeof axes === 'object' && 'x' in axes && 'y' in axes) return axes as CurveAxes;
+    current = (current as { def?: { innerType?: unknown } }).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: readonly CurvePoint[]): number[] {
+  const n = points.length;
+  const secants: number[] = [];
+  for (let i = 0; i < n - 1; i++) {
+    const left = points[i] as CurvePoint;
+    const right = points[i + 1] as CurvePoint;
+    secants.push((right.y - left.y) / (right.x - left.x));
+  }
+  const tangents: number[] = [secants[0] as number];
+  for (let i = 1; i < n - 1; i++) {
+    tangents.push(((secants[i - 1] as number) + (secants[i] as number)) / 2);
+  }
+  tangents.push(secants[n - 2] as number);
+
+  for (let i = 0; i < n - 1; i++) {
+    const secant = secants[i] as number;
+    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] as number) / secant;
+    let beta = (tangents[i + 1] as number) / 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: CurveValue, x: number): number {
+  const points = value.points;
+  if (points.length === 0) return 0;
+  const first = points[0] as CurvePoint;
+  const last = points[points.length - 1] as CurvePoint;
+  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] as CurvePoint).x) i++;
+  const left = points[i] as CurvePoint;
+  const right = points[i + 1] as CurvePoint;
+  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] as number) +
+    (-2 * t3 + 3 * t2) * right.y +
+    (t3 - t2) * span * (tangents[i + 1] as number)
+  );
+}

package/src/data/vite-plugin-data.ts

@@ -38,8 +38,14 @@
  * names the registry file to fix.
  */
 
-import { readdirSync, readFileSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
+// Node built-ins are imported LAZILY (inside `collectDataCheckProblems`),
+// never statically: this module is re-exported by the `@vgai/engine/config`
+// barrel, which every project `*.schema.ts` reaches through its `data-ref`
+// shim — so this module EVALUATES in the browser graph of any world whose
+// schema the game imports. A static `import { … } from 'node:fs'` dies there
+// ("Module node:fs has been externalized for browser compatibility") before
+// the world can mount. The fs work itself only ever runs in Node (vite build
+// / emit-schemas), where the dynamic import resolves normally.
 import type { Plugin } from 'vite';
 import type { z } from 'zod';
 import { parseDataJson, toDataJsonSchema } from './data-asset';
@@ -62,18 +68,38 @@ export interface VgaiDataCheckOptions {
   readonly root?: string;
 }
 
+/** The Node APIs the checks need, resolved lazily — see the import note above. */
+interface NodeIo {
+  readdirSync: typeof import('node:fs')['readdirSync'];
+  readFileSync: typeof import('node:fs')['readFileSync'];
+  statSync: typeof import('node:fs')['statSync'];
+  join: typeof import('node:path')['join'];
+  relative: typeof import('node:path')['relative'];
+}
+
+async function loadNodeIo(): Promise<NodeIo> {
+  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: string): string[] {
+function findDataFiles(io: NodeIo, dir: string): string[] {
   let entries: string[];
   try {
-    entries = readdirSync(dir);
+    entries = io.readdirSync(dir) as string[];
   } catch {
     return [];
   }
   const out: string[] = [];
   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);
   }
   return out;
@@ -116,6 +142,7 @@ interface ParsedDataFiles {
 }
 
 function parseAllDataFiles(
+  io: NodeIo,
   root: string,
   registered: ReadonlySet<string>,
   errors: string[],
@@ -123,15 +150,15 @@ function parseAllDataFiles(
 ): ParsedDataFiles {
   const parsedByStem = new Map<string, unknown>();
   const pathsByStem = new Map<string, string[]>();
-  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) paths.push(rel);
     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') as string));
     } catch (err) {
       errors.push(
         `"${rel}" is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
@@ -167,15 +194,22 @@ function parseAllDataFiles(
  * 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: VgaiDataCheckOptions): {
+export async function collectDataCheckProblems(options: VgaiDataCheckOptions): Promise<{
   errors: string[];
   warnings: string[];
-} {
+}> {
+  const io = await loadNodeIo();
   const root = options.root ?? process.cwd();
   const errors: string[] = [];
   const warnings: string[] = [];
   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) {
@@ -256,8 +290,8 @@ export function vgaiDataCheck(options: VgaiDataCheckOptions): Plugin {
   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) {
         // ONE error carrying every problem — fail loud with the full picture,

package/src/dev/performance-profiler.ts

@@ -109,6 +109,12 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
   let frameSystems: PerformanceSpan[] = [];
   let frameComponents: PerformanceSpan[] = [];
   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;
@@ -177,13 +183,26 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
     set enabled(value: boolean) {
       if (enabled === value) return;
       enabled = value;
+      if (value && !telemetryEnabled) lastFrameStart = 0;
+      publish();
+    },
+    get telemetryEnabled() {
+      return telemetryEnabled;
+    },
+    set telemetryEnabled(value: boolean) {
+      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();
@@ -197,7 +216,7 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
       publish();
     },
     beginFrame() {
-      if (!enabled) return;
+      if (!enabled && !telemetryEnabled) return;
       currentPhases.clear();
       currentSystems.clear();
       currentComponents.clear();
@@ -293,7 +312,7 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
       };
     },
     endFrame() {
-      if (!enabled) return;
+      if (!enabled && !telemetryEnabled) return;
       const timestamp = now();
       const intervalMs = lastFrameStart === 0 ? 0 : frameStart - lastFrameStart;
       lastFrameStart = frameStart;

package/src/dev/register-render-vitals.ts

@@ -6,10 +6,19 @@
  * through `vgai eval`, and `game.providers()`/`game.commands()` to discover
  * them without being told they exist.
  *
- * Engine-owned and first-party, seeded by the three adapter
- * (`adapter/setup-three-root-adapter.ts`) at the same spot it seeds
- * `systemAdapters.renderDebug` — a game writes nothing to get these, and there
- * is no capability to install. The measurement half is `dev/render-vitals.ts`
+ * Engine-owned and first-party, seeded by BOTH three-root mount paths — a game
+ * writes nothing to get these, and there is no capability to install:
+ *  - `adapter/setup-three-root-adapter.ts` (the classic imperative
+ *    `setup(ctx)` world), at the same spot it seeds
+ *    `systemAdapters.renderDebug`;
+ *  - `world3d-react/r3f-adapter.tsx` (a TSX/R3F world — the shape EVERY
+ *    scaffolded project's three root has), right after fiber's first commit
+ *    resolves the scene.
+ * Both is the whole point and not redundancy: they are two independent mounts
+ * onto the same `Game`, and a door wired into only one of them is a door half
+ * the engine's worlds never get (issue #1518 — the R3F half was dark
+ * everywhere, found in the field on a package-native project).
+ * The measurement half is `dev/render-vitals.ts`
  * (derived entirely from profiler frames); the address-book half is
  * `dev/render-census.ts` (pure walks over the live scene). This module is only
  * the wiring between them and the registry.
@@ -27,9 +36,11 @@
  *                        the drawing buffer halves was never fill-bound.
  *
  * ── GATING ──────────────────────────────────────────────────────────────────
- * The caller gates. `setup-three-root-adapter.ts` calls this only under
- * `devLayersEnabled()` (`runtime/dev-layers.ts` — the ONE owner of "is this a
- * dev context"), so a ship build registers nothing and pays nothing.
+ * The caller gates. Both seeders call this only under `devLayersEnabled()`
+ * (`runtime/dev-layers.ts` — the ONE owner of "is this a dev context"), so a
+ * ship build registers nothing and pays nothing. Each also requires a `Game`
+ * shell (there is no profiler to fold without one) and a non-headless mount
+ * (nothing brackets a submission, so the readings could only ever be empty).
  *
  * ── RESOURCE OWNERSHIP ──────────────────────────────────────────────────────
  * OWNER: {@link registerRenderVitals}'s caller. It allocates one
@@ -112,7 +123,26 @@ export function registerRenderVitals(
   const taken = registry.adapter
     .providers()
     .some((provider) => provider.name === RENDER_VITALS_PROVIDER);
-  if (taken) return null;
+  if (taken) {
+    // Loud, by name. This branch used to return `null` in silence, and a
+    // silent decline is indistinguishable from a door that was never seeded —
+    // which is precisely how issue #1518 stayed a mystery through a field
+    // session: every hypothesis about WHY the door was closed had to be
+    // guessed, because nothing on any path said anything. It costs one line to
+    // make the one legitimate decline explain itself, and the same line names
+    // the mount/teardown OVERLAP case (a re-mount seeding before the outgoing
+    // mount's `strip()` runs), where the second world would otherwise lose the
+    // door and no log would mention it.
+    console.warn(
+      `[render-vitals] world "${worldId}" did not get the ${RENDER_VITALS_PROVIDER} door: ` +
+        'another live world already owns it (the names are fixed, so the first three root to ' +
+        'mount wins). Its draws still fold into the readings — the profiler is game-scoped — ' +
+        'but render.census/families/toggle address the owning root. If this world IS the ' +
+        'current one, the previous mount was torn down AFTER this one seeded and its ' +
+        'strip() took the door with it.',
+    );
+    return null;
+  }
 
   const vitals = createRenderVitals(profiler);
   const debug = registry.forRoot(worldId);

package/src/ecs/user-data.ts

@@ -76,18 +76,48 @@
  *                           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`. */
@@ -112,6 +142,8 @@ export type EditorHelperType =
   | 'particle-shape'
   | 'pivot'
   | 'navmesh'
+  | 'constraints'
+  | 'reflection-probes'
   | 'skeletons';
 
 /**
@@ -143,12 +175,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
@@ -189,12 +232,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',
 } as const satisfies Record<UserDataKey, string>;

package/src/index.ts

@@ -20,13 +20,12 @@
  *   - 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,
@@ -35,7 +34,7 @@ export type {
   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,

package/src/manifest/index.ts

@@ -8,21 +8,9 @@ export {
   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';
 
 // `loadGameManifestFile` (Node-only, reads `path` via `node:fs`) is
 // deliberately NOT re-exported here — this barrel must stay import-safe for