@vgai/engine 0.2.0 → 0.3.0

package/dist/core/system-runner.js

@@ -0,0 +1,286 @@
+import { PHASE_ORDER } from './types';
+/**
+ * Ordered system execution by named phase.
+ *
+ * Systems are registered with a phase name. When `run(dt)` is called, all
+ * phases execute in `PHASE_ORDER` via `runPhase(phase, dt)`. Within a phase,
+ * `runPhase` executes three ordered buckets (GAME-ROOT-DESIGN.md §4, T7.1
+ * slice 2):
+ *
+ *   1. **engine** — everything `add()`/`register()`ed at or before the last
+ *      `markEngineBoundary()` call, or EVERYTHING if no boundary has ever
+ *      been marked (the world2d-silo case: it never calls
+ *      `markEngineBoundary`, so its systems are all "engine").
+ *   2. **componentTick** — the single per-phase slot set via
+ *      `setComponentTick(phase, fn)`. Component ticks are engine
+ *      infrastructure: they always run after every engine system and before
+ *      every game system in that phase, REGARDLESS of when
+ *      `setComponentTick` was called relative to other `add()` calls. This
+ *      is what makes "engine systems run before component ticks" a
+ *      structural guarantee rather than a registration-order convention
+ *      (see `component-manager.ts`, which registers its tick this way).
+ *   3. **game** — everything `add()`/`register()`ed AFTER the last
+ *      `markEngineBoundary()` call.
+ *
+ * Within each bucket, systems run in registration order.
+ */
+export function createSystemRunner() {
+    const systems = new Map();
+    const registered = [];
+    const componentTicks = new Map();
+    // Initialize all phases with empty arrays / no component tick.
+    for (const phase of PHASE_ORDER) {
+        systems.set(phase, []);
+        componentTicks.set(phase, null);
+    }
+    // Membership bookkeeping for `markEngineBoundary()` (T7.2 review fix —
+    // replaces the old length/index-snapshot bookkeeping, which broke if a
+    // pre-boundary "engine" entry was ever removed: shrinking the list would
+    // shift a later "game" entry underneath the recorded length, misclassifying
+    // it as engine). `engineFns`/`engineRegistered` instead record WHICH
+    // specific function/system was present at the last `markEngineBoundary()`
+    // call — membership survives arbitrary removal of any other entry,
+    // regardless of position. `boundaryMarked` is false until the first mark
+    // (mirrors the old `boundary === null`: everything is "engine" pre-mark —
+    // the world2d-silo case, which never marks a boundary). Component-tick
+    // slots (`setComponentTick`) are NOT part of this bookkeeping at all — they
+    // are engine infrastructure and survive `removeAllNonEngine()`
+    // unconditionally.
+    let boundaryMarked = false;
+    const engineFns = new Map();
+    for (const phase of PHASE_ORDER)
+        engineFns.set(phase, new Set());
+    const engineRegistered = new Set();
+    /** Run one system function, isolating a throw so it never wedges the frame. */
+    function runOne(fn, phase, dt) {
+        try {
+            fn(dt);
+        }
+        catch (err) {
+            const label = fn.name ? `"${fn.name}"` : '(anonymous)';
+            console.error(`[system-runner] system ${label} in phase "${phase}" threw:`, err);
+        }
+    }
+    return {
+        /**
+         * Register a bare system function in a specific phase.
+         * Systems within the same phase run in the order they were added.
+         */
+        add(phase, fn) {
+            const list = systems.get(phase);
+            if (!list) {
+                throw new Error(`Unknown phase: ${phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
+            }
+            list.push(fn);
+        },
+        /**
+         * Remove a bare system function from a phase. Also drops it from the
+         * engine-membership set (if present) — the fix for the length-based
+         * bookkeeping bug: removing this has no effect on how any OTHER entry
+         * (before or after it) is classified, since classification is now
+         * per-function membership, not position.
+         */
+        remove(phase, fn) {
+            const list = systems.get(phase);
+            if (!list)
+                return;
+            const idx = list.indexOf(fn);
+            if (idx !== -1)
+                list.splice(idx, 1);
+            engineFns.get(phase)?.delete(fn);
+        },
+        /**
+         * Register a lifecycle system. Adds its update to the correct phase.
+         * Call runInit() after all systems are registered to invoke init hooks.
+         */
+        register(system) {
+            const list = systems.get(system.phase);
+            if (!list) {
+                throw new Error(`Unknown phase: ${system.phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
+            }
+            list.push(system.update);
+            registered.push(system);
+        },
+        /**
+         * Unregister a lifecycle system. Removes its update and calls dispose.
+         */
+        unregister(system) {
+            const list = systems.get(system.phase);
+            if (list) {
+                const idx = list.indexOf(system.update);
+                if (idx !== -1)
+                    list.splice(idx, 1);
+            }
+            engineFns.get(system.phase)?.delete(system.update);
+            const regIdx = registered.indexOf(system);
+            if (regIdx !== -1)
+                registered.splice(regIdx, 1);
+            engineRegistered.delete(system);
+            system.dispose?.();
+        },
+        /**
+         * Register the ONE component-tick function for a phase (T7.1 slice 2).
+         * Component ticks are engine infrastructure, not a bare `add()`ed
+         * system: they always execute after every engine-bucket system and
+         * before every game-bucket system in that phase (see `runPhase`),
+         * they are never touched by `removeAllNonEngine()`, and they do not
+         * count toward `markEngineBoundary()`'s bookkeeping. Throws if a tick
+         * is already set for this phase — at most one component manager may
+         * own a phase's tick slot.
+         */
+        setComponentTick(phase, fn) {
+            if (!componentTicks.has(phase)) {
+                throw new Error(`Unknown phase: ${phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
+            }
+            if (componentTicks.get(phase)) {
+                throw new Error(`[system-runner] setComponentTick: phase "${phase}" already has a component tick registered`);
+            }
+            componentTicks.set(phase, fn);
+        },
+        /**
+         * Call init() on all registered lifecycle systems, in phase order.
+         * Call once after scene load, before the first game loop tick.
+         */
+        runInit() {
+            const sorted = [...registered].sort((a, b) => PHASE_ORDER.indexOf(a.phase) - PHASE_ORDER.indexOf(b.phase));
+            for (const sys of sorted) {
+                sys.init?.();
+            }
+        },
+        /**
+         * Call dispose() on all registered lifecycle systems and remove them.
+         */
+        runDispose() {
+            for (const sys of registered) {
+                const list = systems.get(sys.phase);
+                if (list) {
+                    const idx = list.indexOf(sys.update);
+                    if (idx !== -1)
+                        list.splice(idx, 1);
+                }
+                sys.dispose?.();
+            }
+            registered.length = 0;
+        },
+        /**
+         * Run ONE phase's three ordered buckets — engine, componentTick, game
+         * (see the module doc comment). Each system call is isolated: a
+         * throwing system is loudly logged (never swallowed) but does not stop
+         * its siblings in the same bucket, a later bucket in this phase, or a
+         * later phase, from running this frame.
+         *
+         * Public — the Game root's frame executor (`runtime/game.ts`) calls this
+         * directly per (phase, world); `run(dt)` below is just a loop over it,
+         * preserved for the world2d silo and any direct caller.
+         */
+        runPhase(phase, dt) {
+            const list = systems.get(phase);
+            if (!list) {
+                throw new Error(`Unknown phase: ${phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
+            }
+            // Partition by MEMBERSHIP, not position: everything in this phase's
+            // `engineFns` set (or, if no boundary has ever been marked, everything —
+            // the world2d-silo case) runs immediately, in list order, as it's
+            // encountered; everything else is queued into `gameFns` (also in list
+            // order) and run after the component tick. Because classification is
+            // per-function rather than "index < some remembered length", removing
+            // ANY entry via `remove()` — including a pre-boundary "engine" one —
+            // cannot shift a later game system into the engine bucket.
+            const engineSet = engineFns.get(phase);
+            const gameFns = [];
+            for (const fn of list) {
+                if (boundaryMarked && !engineSet.has(fn)) {
+                    gameFns.push(fn);
+                }
+                else {
+                    runOne(fn, phase, dt);
+                }
+            }
+            const tick = componentTicks.get(phase);
+            if (tick)
+                runOne(tick, phase, dt);
+            for (const fn of gameFns) {
+                runOne(fn, phase, dt);
+            }
+        },
+        /**
+         * Run all phases in order, via `runPhase`.
+         */
+        run(dt) {
+            for (const phase of PHASE_ORDER) {
+                this.runPhase(phase, dt);
+            }
+        },
+        /**
+         * Mark everything registered so far (via `add()`/`register()`, in every
+         * phase) as "engine" — infrastructure that must survive a warm restart.
+         * Call once, right after mount finishes wiring engine-level systems and
+         * BEFORE any game (`setup()`/scene load) registers its own. `hotReload`
+         * calls `removeAllNonEngine()` on every restart, which only ever removes
+         * what was added after this mark. Component-tick slots (`setComponentTick`)
+         * are unaffected — they are never part of this boundary.
+         */
+        markEngineBoundary() {
+            for (const phase of PHASE_ORDER) {
+                const set = engineFns.get(phase);
+                for (const fn of systems.get(phase))
+                    set.add(fn);
+            }
+            for (const sys of registered)
+                engineRegistered.add(sys);
+            boundaryMarked = true;
+        },
+        /**
+         * Bulk-remove every system registered after the last `markEngineBoundary()`
+         * call — both bare `add()`ed functions and lifecycle `register()`ed systems
+         * (the latter get `dispose()`d, mirroring `unregister()`). A no-op if no
+         * boundary has been marked. Idempotent: calling it again with nothing new
+         * registered since is a safe no-op. Component-tick slots are NEVER cleared
+         * by this — they are engine infrastructure, not game content.
+         *
+         * This is what makes a warm restart (`hotReload`) safe to call N times
+         * without accumulating duplicate systems/listeners — each restart's
+         * outgoing game systems are fully removed before the new one registers its
+         * own, while the engine systems (input/physics/render/the ComponentManager
+         * tick/...) registered before the boundary are never touched.
+         */
+        removeAllNonEngine() {
+            if (!boundaryMarked)
+                return;
+            // Membership-based, same reasoning as runPhase: partition by whether
+            // each entry is in the engine set, not by a remembered length/index.
+            const keptRegistered = registered.filter((sys) => engineRegistered.has(sys));
+            const removedRegistered = registered.filter((sys) => !engineRegistered.has(sys));
+            registered.length = 0;
+            registered.push(...keptRegistered);
+            for (const sys of removedRegistered) {
+                sys.dispose?.();
+            }
+            for (const phase of PHASE_ORDER) {
+                const list = systems.get(phase);
+                const engineSet = engineFns.get(phase);
+                const kept = list.filter((fn) => engineSet.has(fn));
+                list.length = 0;
+                list.push(...kept);
+            }
+        },
+        /**
+         * Total system-function count, optionally scoped to one phase. Includes
+         * component-tick slots (a set slot counts as 1 per phase it occupies).
+         * Test/introspection helper — used to assert a warm restart doesn't
+         * accumulate systems (see `removeAllNonEngine`).
+         */
+        count(phase) {
+            if (phase) {
+                return (systems.get(phase)?.length ?? 0) + (componentTicks.get(phase) ? 1 : 0);
+            }
+            let total = 0;
+            for (const [p, list] of systems) {
+                total += list.length;
+                if (componentTicks.get(p))
+                    total += 1;
+            }
+            return total;
+        },
+    };
+}

package/dist/core/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * System execution phases, in order.
+ * Each frame, systems run in this exact sequence.
+ */
+export declare const SystemPhase: {
+    readonly INPUT: "input";
+    readonly PRE_PHYSICS: "prePhysics";
+    readonly PHYSICS: "physics";
+    readonly POST_PHYSICS: "postPhysics";
+    readonly GAME_LOGIC: "gameLogic";
+    readonly ANIMATION: "animation";
+    readonly PRE_RENDER: "preRender";
+    readonly RENDER: "render";
+};
+export type SystemPhaseName = (typeof SystemPhase)[keyof typeof SystemPhase];
+/** Order of phase execution */
+export declare const PHASE_ORDER: SystemPhaseName[];
+/** A system is just a function that takes delta time */
+export type SystemFn = (dt: number) => void;
+/** A lifecycle system with init/update/dispose hooks. */
+export interface SystemDef {
+    /** Which phase the update function runs in */
+    phase: SystemPhaseName;
+    /** One-time setup after all entities are spawned, before the first frame */
+    init?(): void;
+    /** Per-frame update */
+    update: SystemFn;
+    /** Cleanup when the system is removed or the scene unloads */
+    dispose?(): void;
+}
+export interface GameLoopConfig {
+    /** Fixed timestep in seconds (default: 1/60) */
+    fixedTimestep?: number;
+    /** Max physics substeps per frame to prevent spiral of death (default: 8) */
+    maxSubSteps?: number;
+    /**
+     * Called once per consumed fixed substep. Rendering (the `render` phase,
+     * last in `PHASE_ORDER`) runs *inside* this call — rendering is
+     * deliberately fixed-rate (decided — D1, `docs/DECISIONS-PENDING.md`),
+     * not a separate per-real-frame step. A real frame whose accumulator
+     * produces zero substeps calls `update` zero times and renders zero times.
+     */
+    update: (dt: number) => void;
+    /**
+     * External-drive mode (I2, `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md`
+     * §15 I2): when `true`, `start()` never arms a `requestAnimationFrame`
+     * chain and never installs the `visibilitychange`/`document.hidden`
+     * auto-stop handler — so a headless/backgrounded capture page cannot have
+     * its loop silently killed by the tab-hidden guard, and `config.update`
+     * is never invoked by wall-clock/RAF timing at all. The caller (a render
+     * harness) drives frames itself instead — see `runtime/render-control.ts`,
+     * which calls a world's phase hooks directly rather than going through
+     * this loop's `update` callback. Default `false` (normal wall-clock RAF
+     * playback, unchanged).
+     */
+    externalDrive?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;;;;CASd,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAE7E,+BAA+B;AAC/B,eAAO,MAAM,WAAW,EAAE,eAAe,EASxC,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,QAAQ,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;AAE5C,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB,8CAA8C;IAC9C,KAAK,EAAE,eAAe,CAAC;IACvB,4EAA4E;IAC5E,IAAI,CAAC,IAAI,IAAI,CAAC;IACd,uBAAuB;IACvB,MAAM,EAAE,QAAQ,CAAC;IACjB,8DAA8D;IAC9D,OAAO,CAAC,IAAI,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB"}

package/dist/core/types.js

@@ -0,0 +1,25 @@
+/**
+ * System execution phases, in order.
+ * Each frame, systems run in this exact sequence.
+ */
+export const SystemPhase = {
+    INPUT: 'input',
+    PRE_PHYSICS: 'prePhysics',
+    PHYSICS: 'physics',
+    POST_PHYSICS: 'postPhysics',
+    GAME_LOGIC: 'gameLogic',
+    ANIMATION: 'animation',
+    PRE_RENDER: 'preRender',
+    RENDER: 'render',
+};
+/** Order of phase execution */
+export const PHASE_ORDER = [
+    SystemPhase.INPUT,
+    SystemPhase.PRE_PHYSICS,
+    SystemPhase.PHYSICS,
+    SystemPhase.POST_PHYSICS,
+    SystemPhase.GAME_LOGIC,
+    SystemPhase.ANIMATION,
+    SystemPhase.PRE_RENDER,
+    SystemPhase.RENDER,
+];

package/dist/data/data-asset.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Data assets — W1 of `docs/DATA-TOOLS-DESIGN.md` (§2.3 consumption API).
+ *
+ * A data asset is designer-tunable game data: a JSON file in the project's
+ * `src/data/`, governed by a Zod schema (`*.schema.ts`, engineer-owned) whose
+ * emitted JSON Schema (`*.schema.json`, see {@link toDataJsonSchema}) gives
+ * VS Code validation via the data file's `"$schema"` first line. Data assets
+ * are immutable at runtime — definitions, not state (§2.1).
+ *
+ * The blessed consumption shape, scaffolded working-at-birth by the project
+ * template (`src/data/` there is the worked example — §6.2):
+ *
+ * ```ts
+ * import raw from './tuning.data.json';
+ * import { TuningSchema } from './tuning.schema';
+ * import { defineData } from '@engine/data/data-asset';
+ *
+ * export const tuning = defineData(TuningSchema, raw, 'src/data/tuning.data.json');
+ * // Vite HMR needs the literal dep path in THIS module (static analysis) —
+ * // this one line is the entire live-tuning wiring (['default'] not .default:
+ * // strict tsconfigs index-signature ModuleNamespace):
+ * import.meta.hot?.accept('./tuning.data.json', (m) => tuning.hotSwap(m?.['default']));
+ * ```
+ *
+ * Game code reads `tuning.get()` inside its update loop (never cache fields
+ * across frames) or `subscribe()`s; an edit to the `.data.json` — from
+ * VS Code, an agent, or the future editor Data tab (W2) — flows through Vite
+ * HMR into the running game with no remount. React worlds/tools get a
+ * `useData` hook with W3's tool-hooks package (deferred with it: the engine
+ * core stays React-free).
+ */
+import { z } from 'zod';
+/**
+ * A live handle to one data asset (§2.3). `get`/`subscribe` are the whole
+ * runtime surface; `hotSwap` exists only for the owning module's
+ * `import.meta.hot.accept` callback.
+ */
+export interface DataHandle<T> {
+    /** Current parsed values. Read every frame — HMR swaps them under you. */
+    get(): T;
+    /**
+     * Called with the new value after every successful hot swap (NOT with the
+     * initial value). Returns an unsubscribe function.
+     */
+    subscribe(fn: (value: T) => void): () => void;
+    /**
+     * HMR entry point — call from the owning module's
+     * `import.meta.hot.accept('<file>.data.json', (m) => handle.hotSwap(m?.default))`.
+     * Parses like load, but a FAILING edit keeps the last good value and
+     * `console.error`s instead of throwing: a typo mid-live-tune must not
+     * crash the running game. Fix the file and save again.
+     */
+    hotSwap(next: unknown): void;
+    /**
+     * The project-relative path this handle was defined with (`defineData`'s
+     * own `sourcePath` argument, populated automatically below) — OPTIONAL so
+     * any hand-rolled structural implementer stays valid. `getRef`
+     * (`./data-ref.ts`) reads this to catch a `getRef(wrongHandle, "stem#key")`
+     * mismatch with a teaching error instead of silently resolving against the
+     * wrong asset; without it, `getRef` just skips that one check.
+     */
+    readonly sourcePath?: string;
+}
+/**
+ * Define a data asset from its Zod schema, the statically imported JSON, and
+ * its project-relative path (used verbatim in error messages, so pass the
+ * real one). Parse-on-load: an invalid file fails loud at import time, naming
+ * the file, every bad path, and the fix (§2.3, §6.5 "errors teach").
+ *
+ * Schema fields should carry `.min/.max/.default/.describe` — the same
+ * annotations `GameComponent.static schema` uses — so the emitted JSON Schema
+ * documents the file and (W2+) the editor renders real widgets.
+ */
+export declare function defineData<S extends z.ZodType>(schema: S, initial: unknown, sourcePath: string): DataHandle<z.output<S>>;
+/**
+ * Emit the JSON Schema interchange artifact for a data asset's Zod schema
+ * (§2.1: `*.schema.json` is EMITTED, never hand-written; D4: generated and
+ * committed by default so VS Code works with no dev server running).
+ *
+ * Wraps `z.toJSONSchema` with `io: 'input'` — the one non-obvious knob:
+ * defaulted fields must be OPTIONAL in the file schema (a data file may omit
+ * them), whereas the default output mode would mark every field `required`
+ * and make VS Code reject valid files. The template's root `emit-schemas.ts`
+ * is the blessed caller (`npm run emit-schemas`).
+ *
+ * The emitted root schema also explicitly ALLOWS the `"$schema"` string
+ * property, mirroring the parse-side strip below: without it, a TABLE
+ * asset's emitted schema (`z.record` → `additionalProperties: <rowSchema>`)
+ * makes VS Code flag the data file's own `"$schema"` line as an invalid row.
+ */
+export declare function toDataJsonSchema(schema: z.ZodType): Record<string, unknown>;
+/**
+ * Parse a raw `.data.json` payload: strips the `"$schema"` interchange line,
+ * validates through the Zod schema, throws the teaching error on failure.
+ * `defineData` uses this internally on load and hot swap; it is exported for
+ * emit/doctor-style scripts (the template's `emit-schemas.ts` validates every
+ * data file through it, so file validation and runtime validation can never
+ * disagree).
+ */
+export declare function parseDataJson<S extends z.ZodType>(schema: S, data: unknown, sourcePath: string): z.output<S>;
+//# sourceMappingURL=data-asset.d.ts.map

package/dist/data/data-asset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-asset.d.ts","sourceRoot":"","sources":["../../src/data/data-asset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,0EAA0E;IAC1E,GAAG,IAAI,CAAC,CAAC;IACT;;;OAGG;IACH,SAAS,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC9C;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAC5C,MAAM,EAAE,CAAC,EACT,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,MAAM,GACjB,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAwBzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQ3E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAC/C,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,MAAM,GACjB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAsBb"}

package/dist/data/data-asset.js

@@ -0,0 +1,122 @@
+/**
+ * Data assets — W1 of `docs/DATA-TOOLS-DESIGN.md` (§2.3 consumption API).
+ *
+ * A data asset is designer-tunable game data: a JSON file in the project's
+ * `src/data/`, governed by a Zod schema (`*.schema.ts`, engineer-owned) whose
+ * emitted JSON Schema (`*.schema.json`, see {@link toDataJsonSchema}) gives
+ * VS Code validation via the data file's `"$schema"` first line. Data assets
+ * are immutable at runtime — definitions, not state (§2.1).
+ *
+ * The blessed consumption shape, scaffolded working-at-birth by the project
+ * template (`src/data/` there is the worked example — §6.2):
+ *
+ * ```ts
+ * import raw from './tuning.data.json';
+ * import { TuningSchema } from './tuning.schema';
+ * import { defineData } from '@engine/data/data-asset';
+ *
+ * export const tuning = defineData(TuningSchema, raw, 'src/data/tuning.data.json');
+ * // Vite HMR needs the literal dep path in THIS module (static analysis) —
+ * // this one line is the entire live-tuning wiring (['default'] not .default:
+ * // strict tsconfigs index-signature ModuleNamespace):
+ * import.meta.hot?.accept('./tuning.data.json', (m) => tuning.hotSwap(m?.['default']));
+ * ```
+ *
+ * Game code reads `tuning.get()` inside its update loop (never cache fields
+ * across frames) or `subscribe()`s; an edit to the `.data.json` — from
+ * VS Code, an agent, or the future editor Data tab (W2) — flows through Vite
+ * HMR into the running game with no remount. React worlds/tools get a
+ * `useData` hook with W3's tool-hooks package (deferred with it: the engine
+ * core stays React-free).
+ */
+import { z } from 'zod';
+/**
+ * Define a data asset from its Zod schema, the statically imported JSON, and
+ * its project-relative path (used verbatim in error messages, so pass the
+ * real one). Parse-on-load: an invalid file fails loud at import time, naming
+ * the file, every bad path, and the fix (§2.3, §6.5 "errors teach").
+ *
+ * Schema fields should carry `.min/.max/.default/.describe` — the same
+ * annotations `GameComponent.static schema` uses — so the emitted JSON Schema
+ * documents the file and (W2+) the editor renders real widgets.
+ */
+export function defineData(schema, initial, sourcePath) {
+    let current = parseDataJson(schema, initial, sourcePath);
+    const subscribers = new Set();
+    return {
+        get: () => current,
+        sourcePath,
+        subscribe(fn) {
+            subscribers.add(fn);
+            return () => subscribers.delete(fn);
+        },
+        hotSwap(next) {
+            let parsed;
+            try {
+                parsed = parseDataJson(schema, next, sourcePath);
+            }
+            catch (err) {
+                // Keep the last good value alive — see the JSDoc on DataHandle.hotSwap.
+                // biome-ignore lint/suspicious/noConsole: deliberate, greppable — a rejected live-tune edit must be loud without crashing the running game (mirrors overlay-report.ts's direct console use)
+                console.error(`[data] hot edit rejected, keeping previous values.\n${String(err)}`);
+                return;
+            }
+            current = parsed;
+            for (const fn of subscribers)
+                fn(current);
+        },
+    };
+}
+/**
+ * Emit the JSON Schema interchange artifact for a data asset's Zod schema
+ * (§2.1: `*.schema.json` is EMITTED, never hand-written; D4: generated and
+ * committed by default so VS Code works with no dev server running).
+ *
+ * Wraps `z.toJSONSchema` with `io: 'input'` — the one non-obvious knob:
+ * defaulted fields must be OPTIONAL in the file schema (a data file may omit
+ * them), whereas the default output mode would mark every field `required`
+ * and make VS Code reject valid files. The template's root `emit-schemas.ts`
+ * is the blessed caller (`npm run emit-schemas`).
+ *
+ * The emitted root schema also explicitly ALLOWS the `"$schema"` string
+ * property, mirroring the parse-side strip below: without it, a TABLE
+ * asset's emitted schema (`z.record` → `additionalProperties: <rowSchema>`)
+ * makes VS Code flag the data file's own `"$schema"` line as an invalid row.
+ */
+export function toDataJsonSchema(schema) {
+    const emitted = z.toJSONSchema(schema, { io: 'input' });
+    if (emitted['type'] === 'object') {
+        const properties = (emitted['properties'] ?? {});
+        properties['$schema'] ??= { type: 'string' };
+        emitted['properties'] = properties;
+    }
+    return emitted;
+}
+/**
+ * Parse a raw `.data.json` payload: strips the `"$schema"` interchange line,
+ * validates through the Zod schema, throws the teaching error on failure.
+ * `defineData` uses this internally on load and hot swap; it is exported for
+ * emit/doctor-style scripts (the template's `emit-schemas.ts` validates every
+ * data file through it, so file validation and runtime validation can never
+ * disagree).
+ */
+export function parseDataJson(schema, data, sourcePath) {
+    // Strip the data file's `"$schema"` interchange line before validating —
+    // singleton (z.object, strip-mode) schemas ignored it by luck, but a TABLE
+    // asset (z.record) would try to validate it as a row and fail.
+    const payload = data !== null && typeof data === 'object' && !Array.isArray(data) && '$schema' in data
+        ? Object.fromEntries(Object.entries(data).filter(([key]) => key !== '$schema'))
+        : data;
+    const result = schema.safeParse(payload);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((issue) => `  - ${issue.path.join('.') || '(root)'}: ${issue.message}`)
+            .join('\n');
+        throw new Error(`Data asset "${sourcePath}" failed its schema:\n${issues}\n` +
+            `Fix the JSON to match the Zod schema (its emitted twin, ` +
+            `"${sourcePath.replace(/\.data\.json$/, '.schema.json')}", documents every field — ` +
+            `re-emit with \`npm run emit-schemas\` if the schema changed). ` +
+            `Worked example: the template's src/data/.`);
+    }
+    return result.data;
+}