@vgai/engine 0.5.4 → 0.5.6

package/dist/core/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 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 — the SIM half. A real frame whose
+     * accumulator produces zero substeps calls this zero times, which is exactly
+     * why {@link GameLoopConfig.render} exists.
+     *
+     * Whether the `render`/`preRender` phases run inside this call is the
+     * CALLER's choice, not this loop's: a host that also passes `render` below
+     * asks `Game.runFrame` to skip them (`skipRenderPhases`), a host that does
+     * not keeps them here as the tail of `PHASE_ORDER`. See `game-loop.ts`'s
+     * module doc.
+     */
+    update: (dt: number) => void;
+    /**
+     * Called EXACTLY ONCE per real (rAF) frame — the PRESENTATION half
+     * (WO-P13, `docs/WORK.md` §2 P13; this is the callback whose absence the
+     * former D1 decision recorded).
+     *
+     * - `alpha` — `accumulator / fixedDt` after this frame's substeps were
+     *   consumed, in `[0, 1]`: how far presentation sits past the last
+     *   completed fixed state. `core/frame-pacing.ts` computes it.
+     * - `displayDt` — this display frame's own delta in seconds, clamped and
+     *   `timeScale`d exactly like the sim's time. Integrate per-display-frame
+     *   motion against this, never against `fixedTimestep`.
+     *
+     * Optional. Never invoked at all in {@link GameLoopConfig.externalDrive}
+     * mode, where `frame()` itself never runs.
+     */
+    render?: (alpha: number, displayDt: number) => void;
+    /**
+     * External-drive mode (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

@@ -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,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;;;;;;;;;;OAUG;IACH,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD;;;;;;;;;;OAUG;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

@@ -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 (§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 every authored 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 (§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 every authored 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 achieved-tier.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;
+}

package/dist/data/data-check-core.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Data-asset integrity core — the PURE half of W5 enforcement ("dangling
+ * `file#key` ref" / §6.7 build-path validation). No filesystem, no vite, no
+ * zod: plain parsed-JSON in, findings out, so BOTH consumers — `vgai
+ * doctor`'s data checks (`packages/editor/src/doctor/data-checks.ts`) and the
+ * build-time plugin (`./vite-plugin-data.ts`) — share one definition of "what
+ * is a ref" and "what counts as dangling" and can never drift apart.
+ *
+ * What is a ref (§2.2): a cross-asset reference is a plain string
+ * `"file#key"` — optionally with a field path, `"tuning#economy.slotGrowth"`
+ * (file `#` key `.` field-path). There is no branded-ref Zod helper shipped
+ * yet (W1 deferred it), so ref DETECTION is by convention, tuned against
+ * false positives: a string is treated as a ref IFF it matches
+ * {@link DATA_REF_PATTERN} AND its `file` prefix names a data asset that
+ * actually exists in the project (`src/data/<file>.data.json`). Strings that
+ * merely contain `#` — hex colors (`"#ff0000"`, no prefix), URLs with
+ * fragments (`/` and `:` never match), musical pitches (`"C#4"` only matches
+ * if a `C.data.json` exists) — never fire. The flip side is deliberate and
+ * honest: a ref whose file prefix names a NONEXISTENT asset is
+ * indistinguishable from an arbitrary string and is NOT flagged ("error if
+ * refs exist yet" — the check only bites once the target file exists).
+ *
+ * `dataRef` (`./data-ref.ts`) now exists, closing that flip side for anyone
+ * who adopts it: a `dataRef(target)` field's EMITTED schema carries
+ * `"x-vgai-ref": target` — a declared intent, independent of whether the
+ * target file currently exists. {@link collectDeclaredRefFields} /
+ * {@link findMissingRefTargets} below walk that (zod-free — plain emitted
+ * JSON Schema in, findings out, same purity contract as the rest of this
+ * module) to catch the §9.4 hole for DECLARED refs: renaming/deleting a
+ * target file used to silently un-check every ref into it; now a declared
+ * ref's target is checked by NAME, not by "does a string happen to look
+ * like one right now." Undeclared conventional-string refs keep the
+ * calibrated behavior above, unchanged.
+ */
+/**
+ * `file#key(.field)*` — prefix must look like an asset stem (letters,
+ * digits, `_`, `-`), key path is dot-separated segments of the same alphabet.
+ */
+export declare const DATA_REF_PATTERN: RegExp;
+/** One ref-shaped string found while walking a data file's parsed JSON. */
+export interface DataRefOccurrence {
+    /** Asset stem of the data file the ref string was found IN (e.g. `"tuning"`). */
+    readonly inAsset: string;
+    /** JSON path of the string inside that file (e.g. `"rows.goblin.drops[2]"`). */
+    readonly atPath: string;
+    /** The full ref string, verbatim (e.g. `"enemies#goblin"`). */
+    readonly ref: string;
+    /** Parsed target asset stem (`"enemies"`). */
+    readonly targetAsset: string;
+    /** Parsed dot-separated key path into the target (`["goblin"]`). */
+    readonly targetKeyPath: readonly string[];
+}
+/** One dangling ref: the target FILE exists but the key path does not resolve in it. */
+export interface DanglingRefFinding extends DataRefOccurrence {
+    /** The first key-path segment that failed to resolve, for the teaching message. */
+    readonly missingSegment: string;
+}
+/**
+ * Walk one data file's parsed JSON and collect every ref-shaped string whose
+ * file prefix names an asset in `assetNames`. The top-level `"$schema"`
+ * interchange line is skipped (it is wiring, not data — same special-casing
+ * as `parseDataJson`'s strip).
+ */
+export declare function collectDataRefs(inAsset: string, json: unknown, assetNames: ReadonlySet<string>): DataRefOccurrence[];
+/**
+ * Find every dangling `file#key(.field)*` ref across a project's data assets.
+ *
+ * @param files parsed `.data.json` payloads keyed by asset stem (the
+ *   filename minus `.data.json` — the same name the ref's prefix uses, §2.2).
+ *   Pass only files that parsed as JSON; unparseable files are already an
+ *   error in their own right and can't be resolved against anyway.
+ * @returns one finding per ref whose target FILE is in `files` but whose key
+ *   path does not fully resolve inside it (a table row that doesn't exist, a
+ *   singleton field path that walks off the object).
+ */
+export declare function findDanglingDataRefs(files: ReadonlyMap<string, unknown>): DanglingRefFinding[];
+/** One `dataRef` field declared in an emitted JSON Schema. */
+export interface DeclaredRefField {
+    /** Dot-separated field path within the schema (e.g. `"drop"`, `"loot.dropTable"`). A table's row-schema fields are reported WITHOUT a row-key segment — the declaration applies to every row alike. */
+    readonly fieldPath: string;
+    /** The asset stem the field's `dataRef(...)` call named. */
+    readonly targetStem: string;
+}
+/** One declared ref whose target stem names no asset that currently exists. */
+export interface MissingRefTargetFinding {
+    readonly fieldPath: string;
+    readonly targetStem: string;
+}
+/**
+ * Walk an emitted data-asset JSON Schema (`toDataJsonSchema`'s output, or the
+ * committed `.schema.json` twin — same shape either way) and collect every
+ * field stamped `"x-vgai-ref": <target>` by `dataRef` (`./data-ref.ts`).
+ * Handles both blessed shapes (spec §2.1): a singleton's `properties`, and a
+ * table's `additionalProperties` row schema — walked with the SAME field
+ * path (a table's declared ref applies uniformly to every row, there is no
+ * per-row schema variation). Nested `properties` inside a ref-declaring
+ * field are not walked further (a ref leaf has no children); nested groups
+ * elsewhere recurse via their own `properties`.
+ */
+export declare function collectDeclaredRefFields(schema: unknown): DeclaredRefField[];
+/**
+ * Every declared ref field whose target stem names no asset in
+ * `assetNames` — the §9.4 fix: a `dataRef('items')` field stays flagged if
+ * `items.data.json` is renamed or deleted, independent of whether any
+ * CURRENT value happens to look like an `items#...` string (the gap the
+ * conventional-string calibration above deliberately leaves open).
+ */
+export declare function findMissingRefTargets(declared: readonly DeclaredRefField[], assetNames: ReadonlySet<string>): MissingRefTargetFinding[];
+//# sourceMappingURL=data-check-core.d.ts.map

package/dist/data/data-check-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-check-core.d.ts","sourceRoot":"","sources":["../../src/data/data-check-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAA6D,CAAC;AAE3F,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED,wFAAwF;AACxF,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,mFAAmF;IACnF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAMD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,GAC9B,iBAAiB,EAAE,CAOrB;AA6CD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,kBAAkB,EAAE,CAU9F;AAYD,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,uMAAuM;IACvM,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,+EAA+E;AAC/E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,EAAE,CAI5E;AAwBD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,GAC9B,uBAAuB,EAAE,CAI3B"}

package/dist/data/data-check-core.js

@@ -0,0 +1,177 @@
+/**
+ * Data-asset integrity core — the PURE half of W5 enforcement ("dangling
+ * `file#key` ref" / §6.7 build-path validation). No filesystem, no vite, no
+ * zod: plain parsed-JSON in, findings out, so BOTH consumers — `vgai
+ * doctor`'s data checks (`packages/editor/src/doctor/data-checks.ts`) and the
+ * build-time plugin (`./vite-plugin-data.ts`) — share one definition of "what
+ * is a ref" and "what counts as dangling" and can never drift apart.
+ *
+ * What is a ref (§2.2): a cross-asset reference is a plain string
+ * `"file#key"` — optionally with a field path, `"tuning#economy.slotGrowth"`
+ * (file `#` key `.` field-path). There is no branded-ref Zod helper shipped
+ * yet (W1 deferred it), so ref DETECTION is by convention, tuned against
+ * false positives: a string is treated as a ref IFF it matches
+ * {@link DATA_REF_PATTERN} AND its `file` prefix names a data asset that
+ * actually exists in the project (`src/data/<file>.data.json`). Strings that
+ * merely contain `#` — hex colors (`"#ff0000"`, no prefix), URLs with
+ * fragments (`/` and `:` never match), musical pitches (`"C#4"` only matches
+ * if a `C.data.json` exists) — never fire. The flip side is deliberate and
+ * honest: a ref whose file prefix names a NONEXISTENT asset is
+ * indistinguishable from an arbitrary string and is NOT flagged ("error if
+ * refs exist yet" — the check only bites once the target file exists).
+ *
+ * `dataRef` (`./data-ref.ts`) now exists, closing that flip side for anyone
+ * who adopts it: a `dataRef(target)` field's EMITTED schema carries
+ * `"x-vgai-ref": target` — a declared intent, independent of whether the
+ * target file currently exists. {@link collectDeclaredRefFields} /
+ * {@link findMissingRefTargets} below walk that (zod-free — plain emitted
+ * JSON Schema in, findings out, same purity contract as the rest of this
+ * module) to catch the §9.4 hole for DECLARED refs: renaming/deleting a
+ * target file used to silently un-check every ref into it; now a declared
+ * ref's target is checked by NAME, not by "does a string happen to look
+ * like one right now." Undeclared conventional-string refs keep the
+ * calibrated behavior above, unchanged.
+ */
+/**
+ * `file#key(.field)*` — prefix must look like an asset stem (letters,
+ * digits, `_`, `-`), key path is dot-separated segments of the same alphabet.
+ */
+export const DATA_REF_PATTERN = /^([A-Za-z0-9_-]+)#([A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*)$/;
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Walk one data file's parsed JSON and collect every ref-shaped string whose
+ * file prefix names an asset in `assetNames`. The top-level `"$schema"`
+ * interchange line is skipped (it is wiring, not data — same special-casing
+ * as `parseDataJson`'s strip).
+ */
+export function collectDataRefs(inAsset, json, assetNames) {
+    const out = [];
+    visitForRefs(json, '', true, (node, path) => {
+        const occurrence = asRefOccurrence(inAsset, node, path, assetNames);
+        if (occurrence)
+            out.push(occurrence);
+    });
+    return out;
+}
+/** Depth-first walk over parsed JSON, calling `onString` for every string leaf with its JSON path. */
+function visitForRefs(node, path, topLevel, onString) {
+    if (typeof node === 'string') {
+        onString(node, path);
+        return;
+    }
+    if (Array.isArray(node)) {
+        node.forEach((item, i) => {
+            visitForRefs(item, `${path}[${i}]`, false, onString);
+        });
+        return;
+    }
+    if (isPlainObject(node)) {
+        for (const [key, value] of Object.entries(node)) {
+            if (topLevel && key === '$schema')
+                continue;
+            visitForRefs(value, path ? `${path}.${key}` : key, false, onString);
+        }
+    }
+}
+/** The string is a ref iff it matches the pattern AND its file prefix names a real asset. */
+function asRefOccurrence(inAsset, value, path, assetNames) {
+    const m = DATA_REF_PATTERN.exec(value);
+    if (!m || !assetNames.has(m[1]))
+        return null;
+    return {
+        inAsset,
+        atPath: path || '(root)',
+        ref: value,
+        targetAsset: m[1],
+        targetKeyPath: m[2].split('.'),
+    };
+}
+/**
+ * Find every dangling `file#key(.field)*` ref across a project's data assets.
+ *
+ * @param files parsed `.data.json` payloads keyed by asset stem (the
+ *   filename minus `.data.json` — the same name the ref's prefix uses, §2.2).
+ *   Pass only files that parsed as JSON; unparseable files are already an
+ *   error in their own right and can't be resolved against anyway.
+ * @returns one finding per ref whose target FILE is in `files` but whose key
+ *   path does not fully resolve inside it (a table row that doesn't exist, a
+ *   singleton field path that walks off the object).
+ */
+export function findDanglingDataRefs(files) {
+    const assetNames = new Set(files.keys());
+    const findings = [];
+    for (const [name, json] of files) {
+        for (const occurrence of collectDataRefs(name, json, assetNames)) {
+            const missing = firstUnresolvedSegment(files.get(occurrence.targetAsset), occurrence);
+            if (missing !== null)
+                findings.push({ ...occurrence, missingSegment: missing });
+        }
+    }
+    return findings;
+}
+/** The first key-path segment that fails to resolve in the target payload, or `null` if the whole path resolves. */
+function firstUnresolvedSegment(target, ref) {
+    let node = target;
+    for (const segment of ref.targetKeyPath) {
+        if (!isPlainObject(node) || !(segment in node))
+            return segment;
+        node = node[segment];
+    }
+    return null;
+}
+function asSchemaNode(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * Walk an emitted data-asset JSON Schema (`toDataJsonSchema`'s output, or the
+ * committed `.schema.json` twin — same shape either way) and collect every
+ * field stamped `"x-vgai-ref": <target>` by `dataRef` (`./data-ref.ts`).
+ * Handles both blessed shapes (spec §2.1): a singleton's `properties`, and a
+ * table's `additionalProperties` row schema — walked with the SAME field
+ * path (a table's declared ref applies uniformly to every row, there is no
+ * per-row schema variation). Nested `properties` inside a ref-declaring
+ * field are not walked further (a ref leaf has no children); nested groups
+ * elsewhere recurse via their own `properties`.
+ */
+export function collectDeclaredRefFields(schema) {
+    const out = [];
+    walkForDeclaredRefs(schema, '', out);
+    return out;
+}
+function walkForDeclaredRefs(raw, path, out) {
+    const node = asSchemaNode(raw);
+    if (!node)
+        return;
+    if (typeof node['x-vgai-ref'] === 'string') {
+        out.push({ fieldPath: path || '(root)', targetStem: node['x-vgai-ref'] });
+        return; // a ref leaf — nothing further to walk under it
+    }
+    if (isPlainObject(node.properties)) {
+        for (const [key, child] of Object.entries(node.properties)) {
+            if (key === '$schema')
+                continue;
+            walkForDeclaredRefs(child, path ? `${path}.${key}` : key, out);
+        }
+    }
+    // A table's row schema (`z.record(rowSchema)` emits an object-valued
+    // `additionalProperties`) — same field-path grammar, no row-key segment.
+    if (isPlainObject(node.additionalProperties)) {
+        walkForDeclaredRefs(node.additionalProperties, path, out);
+    }
+}
+/**
+ * Every declared ref field whose target stem names no asset in
+ * `assetNames` — the §9.4 fix: a `dataRef('items')` field stays flagged if
+ * `items.data.json` is renamed or deleted, independent of whether any
+ * CURRENT value happens to look like an `items#...` string (the gap the
+ * conventional-string calibration above deliberately leaves open).
+ */
+export function findMissingRefTargets(declared, assetNames) {
+    return declared
+        .filter((d) => !assetNames.has(d.targetStem))
+        .map((d) => ({ fieldPath: d.fieldPath, targetStem: d.targetStem }));
+}