@vgai/engine 0.5.0 → 0.5.2

package/dist/core/system-runner.js

@@ -1,297 +0,0 @@
-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(observer, scope = 'world') {
-    const systems = new Map();
-    const registered = [];
-    const componentTicks = new Map();
-    const labels = new Map();
-    let anonymousId = 0;
-    // 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) {
-        const label = labels.get(fn) ?? fn.name ?? `anonymous-${++anonymousId}`;
-        labels.set(fn, label);
-        observer?.beginSystem(scope, phase, label);
-        try {
-            fn(dt);
-        }
-        catch (err) {
-            const label = fn.name ? `"${fn.name}"` : '(anonymous)';
-            console.error(`[system-runner] system ${label} in phase "${phase}" threw:`, err);
-        }
-        finally {
-            observer?.endSystem(scope, phase, label);
-        }
-    }
-    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, options) {
-            const list = systems.get(phase);
-            if (!list) {
-                throw new Error(`Unknown phase: ${phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
-            }
-            list.push(fn);
-            labels.set(fn, options?.name ?? fn.name ?? `anonymous-${++anonymousId}`);
-        },
-        /**
-         * 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);
-            labels.set(system.update, system.name ?? system.update.name ?? `anonymous-${++anonymousId}`);
-            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);
-            labels.set(fn, `components.${phase}`);
-        },
-        /**
-         * 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

@@ -1,92 +0,0 @@
-/**
- * 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;
-export interface SystemOptions {
-    /** Stable diagnostic label; falls back to the function name. */
-    readonly name?: string;
-}
-export interface SystemRunObserver {
-    beginSystem(scope: string, phase: SystemPhaseName, name: string): void;
-    endSystem(scope: string, phase: SystemPhaseName, name: string): void;
-}
-/** A lifecycle system with init/update/dispose hooks. */
-export interface SystemDef {
-    /** Stable diagnostic label; falls back to the update function name. */
-    readonly name?: string;
-    /** 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;
-}
-/**
- * Truthful liveness classification for `createGameLoop`'s returned loop
- * (issue #175 — "state must never claim health it cannot observe"). See
- * `GameLoop.liveness`'s doc comment in `game-loop.ts` for the full contract;
- * exported here (rather than only inline on the loop's return type) so
- * callers elsewhere in the engine (`runtime/game.ts`, `runtime/
- * debug-registry.ts`) can name the union without importing `game-loop.ts`
- * as a value.
- *
- * - `'running'` — the rAF chain is armed and `config.update` is being
- *   driven by real frames (or, for an `externalDrive` loop, `start()` has
- *   been called — see that mode's own liveness note below).
- * - `'hidden-paused'` — the T2.1 idle throttle stopped the loop because
- *   `document.hidden` is true; this is deliberate and reversible (resumes
- *   automatically on visibility), but ZERO ticks are advancing right now.
- * - `'stopped'` — `stop()` was called, or `start()` was never called.
- *
- * `isRunning` collapses `'hidden-paused'` and `'stopped'` into the same
- * `false` — exactly the ambiguity that let a hidden-paused game report as
- * healthy ("playing") through every consumer that only read `isRunning`/
- * store-level play state. Read `liveness` wherever "is this game actually
- * advancing" matters.
- */
-export type GameLoopLiveness = 'running' | 'hidden-paused' | 'stopped';
-//# sourceMappingURL=types.d.ts.map

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

@@ -1 +0,0 @@
-{"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,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACvE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACtE;AAED,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,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;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAAC"}

package/dist/core/types.js

@@ -1,25 +0,0 @@
-/**
- * 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

@@ -1,101 +0,0 @@
-/**
- * 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 roots/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

@@ -1 +0,0 @@
-{"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

@@ -1,122 +0,0 @@
-/**
- * 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 roots/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;
-}