@vgai/engine 0.5.4 → 0.5.6

package/dist/pixi/physics-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"physics-registry.d.ts","sourceRoot":"","sources":["../../src/pixi/physics-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,2BAA2B,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB;iBAKtB,SAAS,QAAQ,MAAM,CAAC,SAAS,YAAY,MAAM,CAAC,QAAQ,GAAG,IAAI;iBAInE,SAAS,GAAG,aAAa,GAAG,SAAS;gCAGtB,MAAM,GAAG,SAAS,GAAG,SAAS;oBAG1C,SAAS,GAAG,IAAI;eAKrB,gBAAgB,CAAC,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;mBAG3C,MAAM;aAGT,IAAI;EAKhB;AAED,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/pixi/physics-registry.js

@@ -0,0 +1,38 @@
+/**
+ * Maps PixiJS display objects to their Rapier 2D bodies/colliders and back —
+ * the Pixi analog of `PhysicsRegistry`. Two indexes:
+ *  - `Container → {body, collider}` for the postPhysics transform writer.
+ *  - `colliderHandle → Container` reverse index for collision/trigger dispatch.
+ */
+export function createPhysics2DRegistry() {
+    const byObject = new Map();
+    const byColliderHandle = new Map();
+    return {
+        add(display, body, collider) {
+            byObject.set(display, { body, collider });
+            byColliderHandle.set(collider.handle, display);
+        },
+        get(display) {
+            return byObject.get(display);
+        },
+        getByColliderHandle(handle) {
+            return byColliderHandle.get(handle);
+        },
+        remove(display) {
+            const refs = byObject.get(display);
+            if (refs)
+                byColliderHandle.delete(refs.collider.handle);
+            byObject.delete(display);
+        },
+        entries() {
+            return byObject.entries();
+        },
+        get size() {
+            return byObject.size;
+        },
+        clear() {
+            byObject.clear();
+            byColliderHandle.clear();
+        },
+    };
+}

package/dist/pixi/scene-capture.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Scene capture for the Pixi surface — the PixiJS analog of the three.js render
+ * accessor-trap (`adapter/ingest/scene-capture.ts`).
+ *
+ * An unmodified PixiJS game owns its own `Application`, `stage`, renderer, and
+ * ticker. To inspect/host that live scene with ZERO edits to the game, we trap the
+ * render call and capture the game's `stage` + renderer + app on its first frame.
+ *
+ * Unlike three.js's `WebGLRenderer` (whose `render` is an own-instance property,
+ * forcing a prototype getter/setter), PixiJS's `Application.prototype.render` is a
+ * normal prototype method — the standard ticker render path (`ticker → app.render()`)
+ * goes through it — so a direct prototype wrap suffices.
+ *
+ * CRITICAL (same module-identity gatekeeper as the 3D path): the trap must be
+ * installed on the SAME `pixi.js` module instance the game uses. A bundler/dev-server
+ * that dedupes `pixi.js` makes an ESM game's `import 'pixi.js'` resolve to the host
+ * instance, so it is trapped; a game bundling its own pixi cannot be captured this
+ * way (degrade to iframe-reachable or opaque-embed tiers — see the spec).
+ */
+/** A live Pixi runtime captured from an external PixiJS game. */
+export interface CapturedRuntime2D {
+    /** The game's root stage Container. */
+    stage: unknown;
+    /** The game's PixiJS renderer. */
+    renderer: unknown;
+    /** The game's Application (so the host can pause/resume its ticker). */
+    app: unknown;
+}
+export interface SceneCapture2DHandle {
+    readonly captured: CapturedRuntime2D | null;
+    waitForCapture(timeoutMs?: number): Promise<CapturedRuntime2D>;
+    getDrawCount(): number;
+    /** Pause/resume the captured game's own ticker (loop-host gating). */
+    setPaused(paused: boolean): void;
+    uninstall(): void;
+}
+/**
+ * Install the render trap on `pixiNamespace.Application.prototype.render`. Pass the
+ * host's `pixi.js` namespace so a shared-instance game is trapped. Install once per
+ * ingest session; `uninstall()` on teardown.
+ */
+export declare function installSceneCapture2D(pixiNamespace: unknown): SceneCapture2DHandle;
+//# sourceMappingURL=scene-capture.d.ts.map

package/dist/pixi/scene-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-capture.d.ts","sourceRoot":"","sources":["../../src/pixi/scene-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,kCAAkC;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,GAAG,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC5C,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC/D,YAAY,IAAI,MAAM,CAAC;IACvB,sEAAsE;IACtE,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,SAAS,IAAI,IAAI,CAAC;CACnB;AAMD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,OAAO,GAAG,oBAAoB,CAoElF"}

package/dist/pixi/scene-capture.js

@@ -0,0 +1,92 @@
+/**
+ * Scene capture for the Pixi surface — the PixiJS analog of the three.js render
+ * accessor-trap (`adapter/ingest/scene-capture.ts`).
+ *
+ * An unmodified PixiJS game owns its own `Application`, `stage`, renderer, and
+ * ticker. To inspect/host that live scene with ZERO edits to the game, we trap the
+ * render call and capture the game's `stage` + renderer + app on its first frame.
+ *
+ * Unlike three.js's `WebGLRenderer` (whose `render` is an own-instance property,
+ * forcing a prototype getter/setter), PixiJS's `Application.prototype.render` is a
+ * normal prototype method — the standard ticker render path (`ticker → app.render()`)
+ * goes through it — so a direct prototype wrap suffices.
+ *
+ * CRITICAL (same module-identity gatekeeper as the 3D path): the trap must be
+ * installed on the SAME `pixi.js` module instance the game uses. A bundler/dev-server
+ * that dedupes `pixi.js` makes an ESM game's `import 'pixi.js'` resolve to the host
+ * instance, so it is trapped; a game bundling its own pixi cannot be captured this
+ * way (degrade to iframe-reachable or opaque-embed tiers — see the spec).
+ */
+/**
+ * Install the render trap on `pixiNamespace.Application.prototype.render`. Pass the
+ * host's `pixi.js` namespace so a shared-instance game is trapped. Install once per
+ * ingest session; `uninstall()` on teardown.
+ */
+export function installSceneCapture2D(pixiNamespace) {
+    const PIXI = pixiNamespace;
+    const proto = PIXI.Application.prototype;
+    let captured = null;
+    let drawCount = 0;
+    const waiters = [];
+    const priorRender = Object.getOwnPropertyDescriptor(proto, 'render');
+    const realRender = proto['render'];
+    Object.defineProperty(proto, 'render', {
+        configurable: true,
+        writable: true,
+        value: function (...args) {
+            drawCount++;
+            const stage = this['stage'];
+            if (!captured && stage) {
+                captured = { stage, renderer: this['renderer'], app: this };
+                for (const resolve of waiters.splice(0))
+                    resolve(captured);
+            }
+            return realRender?.apply(this, args);
+        },
+    });
+    return {
+        get captured() {
+            return captured;
+        },
+        getDrawCount() {
+            return drawCount;
+        },
+        setPaused(paused) {
+            const app = captured?.app;
+            if (!app?.ticker)
+                return;
+            if (paused)
+                app.ticker.stop();
+            else
+                app.ticker.start();
+        },
+        waitForCapture(timeoutMs = 10_000) {
+            if (captured)
+                return Promise.resolve(captured);
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    const i = waiters.indexOf(wrapped);
+                    if (i >= 0)
+                        waiters.splice(i, 1);
+                    reject(new Error(`pixi scene capture timed out after ${timeoutMs}ms — the game never ` +
+                        `rendered, or it bundles its own (un-shared) copy of pixi.js.`));
+                }, timeoutMs);
+                const wrapped = (rt) => {
+                    clearTimeout(timer);
+                    resolve(rt);
+                };
+                waiters.push(wrapped);
+            });
+        },
+        uninstall() {
+            if (priorRender)
+                Object.defineProperty(proto, 'render', priorRender);
+            else if (realRender)
+                Object.defineProperty(proto, 'render', {
+                    configurable: true,
+                    writable: true,
+                    value: realRender,
+                });
+        },
+    };
+}

package/dist/pixi/system-adapters.d.ts

@@ -0,0 +1,16 @@
+import type { Container } from 'pixi.js';
+import type { Physics2DRegistry } from './physics-registry';
+/**
+ * PhysicsAdapter2D — the Pixi analog of the 3D PhysicsAdapter (rapier-physics-adapter).
+ * Lets the editor coordinate editing of a Rapier-2D-driven entity WITHOUT owning the
+ * simulation: report transform ownership, then freeze → commit → unfreeze so a drag
+ * sticks instead of being stomped by the next physics step.
+ */
+export interface PhysicsAdapter2D {
+    ownerOf(display: Container): 'physics' | 'none';
+    freeze(display: Container): void;
+    commit(display: Container, position: [number, number], rotation: number): void;
+    unfreeze(display: Container): void;
+}
+export declare function createPhysicsAdapter2D(physics: Physics2DRegistry): PhysicsAdapter2D;
+//# sourceMappingURL=system-adapters.d.ts.map

package/dist/pixi/system-adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-adapters.d.ts","sourceRoot":"","sources":["../../src/pixi/system-adapters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAChD,MAAM,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IACjC,MAAM,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/E,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;CACpC;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAgCnF"}

package/dist/pixi/system-adapters.js

@@ -0,0 +1,37 @@
+export function createPhysicsAdapter2D(physics) {
+    // Remember each frozen body's prior type so unfreeze restores it.
+    const frozen = new WeakMap();
+    return {
+        ownerOf(display) {
+            const refs = physics.get(display);
+            if (!refs)
+                return 'none';
+            return refs.body.isDynamic() || refs.body.isKinematic() ? 'physics' : 'none';
+        },
+        freeze(display) {
+            const refs = physics.get(display);
+            if (!refs)
+                return;
+            frozen.set(display, refs.body.bodyType());
+            // Kinematic-position bodies hold a pose without being driven by forces.
+            refs.body.setBodyType(2 /* KinematicPositionBased */, true);
+        },
+        commit(display, position, rotation) {
+            const refs = physics.get(display);
+            if (!refs)
+                return;
+            refs.body.setTranslation({ x: position[0], y: position[1] }, true);
+            refs.body.setRotation(rotation, true);
+        },
+        unfreeze(display) {
+            const refs = physics.get(display);
+            if (!refs)
+                return;
+            const prior = frozen.get(display);
+            if (prior !== undefined) {
+                refs.body.setBodyType(prior, true);
+                frozen.delete(display);
+            }
+        },
+    };
+}

package/dist/react/unmanaged-root-detector.d.ts

@@ -0,0 +1,18 @@
+export interface UnmanagedReactRootFinding {
+    readonly file: string;
+    readonly line: number;
+    readonly api: 'createRoot' | 'hydrateRoot' | 'ReactDOM.render';
+}
+/**
+ * Find project-owned React DOM root creation. VGAI hosts React through
+ * manifest adapter roots, so any of these calls in game source creates an
+ * unmanaged second lifecycle and is a hard validation error — except in the
+ * project's own dom-root adapter (see {@link DOM_ROOT_ADAPTER_DIR}).
+ *
+ * The exemption lives HERE, in the detector, rather than in either caller:
+ * the editor's validate-on-change watcher and `vgai validate` both scan the
+ * same tree, and a rule that means two different things depending on who asks
+ * is worse than no rule.
+ */
+export declare function detectUnmanagedReactRoots(source: string, file: string): UnmanagedReactRootFinding[];
+//# sourceMappingURL=unmanaged-root-detector.d.ts.map

package/dist/react/unmanaged-root-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unmanaged-root-detector.d.ts","sourceRoot":"","sources":["../../src/react/unmanaged-root-detector.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,aAAa,GAAG,iBAAiB,CAAC;CAChE;AAwBD;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,yBAAyB,EAAE,CAgD7B"}

package/dist/react/unmanaged-root-detector.js

@@ -0,0 +1,70 @@
+function lineAt(source, offset) {
+    return source.slice(0, offset).split('\n').length;
+}
+/**
+ * The project's own `dom`-root adapter implementation, which is ALLOWED to
+ * create a React root because creating it is the whole job.
+ *
+ * The rule here is "a React root must come from a declared manifest root, not
+ * from game code mounting a second lifecycle beside it". That held trivially
+ * while the only `createRoot` in existence lived in the engine. It stopped
+ * holding when the `react-root` capability moved INTO the project (`vgai add
+ * react-root`): its `createRoot` is precisely what serves a declared `dom`
+ * root — the opposite of bypassing the manifest.
+ *
+ * Matched on the capability's DIRECTORY rather than a filename, so that
+ * editing the copied source — the entire point of the copied-source model —
+ * cannot re-arm the rule against itself. A Vue or Svelte replacement never
+ * trips it at all: only React DOM's own API is detected.
+ */
+const DOM_ROOT_ADAPTER_DIR = /(^|[/\\])src[/\\]lib[/\\]react-root[/\\]/;
+/**
+ * Find project-owned React DOM root creation. VGAI hosts React through
+ * manifest adapter roots, so any of these calls in game source creates an
+ * unmanaged second lifecycle and is a hard validation error — except in the
+ * project's own dom-root adapter (see {@link DOM_ROOT_ADAPTER_DIR}).
+ *
+ * The exemption lives HERE, in the detector, rather than in either caller:
+ * the editor's validate-on-change watcher and `vgai validate` both scan the
+ * same tree, and a rule that means two different things depending on who asks
+ * is worse than no rule.
+ */
+export function detectUnmanagedReactRoots(source, file) {
+    if (DOM_ROOT_ADAPTER_DIR.test(file))
+        return [];
+    const findings = [];
+    const aliases = new Map();
+    for (const match of source.matchAll(/import\s*\{([^}]*)\}\s*from\s*['"]react-dom\/client['"]/g)) {
+        for (const member of (match[1] ?? '').split(',')) {
+            const parsed = member.trim().match(/^(createRoot|hydrateRoot)(?:\s+as\s+([\w$]+))?$/);
+            if (parsed)
+                aliases.set(parsed[2] ?? parsed[1], parsed[1]);
+        }
+    }
+    for (const [alias, api] of aliases) {
+        const call = new RegExp(`\\b${alias.replace(/[$]/g, '\\$&')}\\s*\\(`, 'g');
+        for (const match of source.matchAll(call)) {
+            findings.push({ file, line: lineAt(source, match.index ?? 0), api });
+        }
+    }
+    const namespaceNames = new Set();
+    for (const match of source.matchAll(/import\s+(?:\*\s+as\s+|)([\w$]+)\s+from\s*['"]react-dom(?:\/client)?['"]/g)) {
+        namespaceNames.add(match[1]);
+    }
+    namespaceNames.add('ReactDOM');
+    for (const name of namespaceNames) {
+        for (const api of ['createRoot', 'hydrateRoot', 'render']) {
+            const call = new RegExp(`\\b${name}\\.${api}\\s*\\(`, 'g');
+            for (const match of source.matchAll(call)) {
+                findings.push({
+                    file,
+                    line: lineAt(source, match.index ?? 0),
+                    api: api === 'render' ? 'ReactDOM.render' : api,
+                });
+            }
+        }
+    }
+    return findings.filter((finding, index) => findings.findIndex((candidate) => candidate.file === finding.file &&
+        candidate.line === finding.line &&
+        candidate.api === finding.api) === index);
+}

package/dist/react/use-data.d.ts

@@ -0,0 +1,60 @@
+/**
+ * React hooks for data assets — the tool-hooks half, shipped with W4 (dock
+ * tools).
+ *
+ * Lives under `packages/engine/src/react/` deliberately: this is the ONE
+ * directory of the engine allowed to value-import react (colocated with
+ * `game-state.tsx` per the react-free-core rule proved by
+ * `test/react-core-import-ban.test.ts`). Game roots that aren't react keep
+ * using `DataHandle.get()`/`subscribe()` directly (§2.3).
+ *
+ * - {@link useData} — subscribe a component to any W1 `DataHandle`; works in
+ *   project tools, react roots, and HUD overlays alike.
+ * - {@link writeData} — EDITOR-TOOL plumbing: write a whole `.data.json`
+ *   back through the editor dev server, closing the live-tuning loop
+ *   (widget → file write → Vite HMR → `hotSwap` → {@link useData} re-render
+ *   → the running game reads the new value). Not for game code.
+ */
+import type { DataHandle } from '../data/data-asset';
+/**
+ * Read a data asset's current values and re-render whenever a hot edit lands
+ * (§3.3). A thin `useSyncExternalStore` over the handle's
+ * `subscribe`/`get` — any `defineData` handle works, no provider needed:
+ *
+ * ```tsx
+ * import { tuning } from '../data/tuning';
+ * const values = useData(tuning);   // fresh parsed object after every hotSwap
+ * ```
+ *
+ * `get()` returns the same reference between successful hot swaps, so this
+ * re-renders exactly once per accepted edit and never in between.
+ */
+export declare function useData<T>(handle: DataHandle<T>): T;
+/**
+ * Write a data asset's ENTIRE new value back to its `.data.json` — the write
+ * half of a project tool's live-tuning loop (§3.3, D1: writes are file
+ * writes, always). POSTs to the editor dev server's `/__editor/data-file`
+ * route (see its doc comment in `packages/editor/server/editor-server.ts`),
+ * which accepts only `src/data/**\/*.data.json` and writes immediately; the
+ * running game then receives the change through the normal `.data.json` HMR
+ * path, exactly as if VS Code had saved the file.
+ *
+ * ```tsx
+ * // inside a tool's onChange — spread the live values, replace one field:
+ * void writeData('src/data/tuning.data.json', { ...tuning.get(), gravity: v });
+ * ```
+ *
+ * FOR TOOLS, NOT GAME CODE: data assets are immutable at runtime (§2.1) —
+ * runtime state belongs in your game's own store, never written back into
+ * data files. Outside a running editor there is no `/__editor` server, so
+ * this rejects with a teaching error (a shipped game could never reach the
+ * route anyway — builds strip `src/tools/` entirely, §4).
+ *
+ * Serialization matches the editor Data panel's diff-minimal contract:
+ * `"$schema"` first, 2-space indent, trailing newline. When `value` carries
+ * no `"$schema"` key (the common case — `DataHandle.get()` strips it), the
+ * conventional sibling reference (`./<name>.schema.json`, §2.1) is restored
+ * so a tool write never silently drops VS Code validation from the file.
+ */
+export declare function writeData(projectRelativePath: string, value: Record<string, unknown>): Promise<void>;
+//# sourceMappingURL=use-data.d.ts.map

package/dist/react/use-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-data.d.ts","sourceRoot":"","sources":["../../src/react/use-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAKnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,SAAS,CAC7B,mBAAmB,EAAE,MAAM,EAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC,CAqDf"}

package/dist/react/use-data.js

@@ -0,0 +1,101 @@
+/**
+ * React hooks for data assets — the tool-hooks half, shipped with W4 (dock
+ * tools).
+ *
+ * Lives under `packages/engine/src/react/` deliberately: this is the ONE
+ * directory of the engine allowed to value-import react (colocated with
+ * `game-state.tsx` per the react-free-core rule proved by
+ * `test/react-core-import-ban.test.ts`). Game roots that aren't react keep
+ * using `DataHandle.get()`/`subscribe()` directly (§2.3).
+ *
+ * - {@link useData} — subscribe a component to any W1 `DataHandle`; works in
+ *   project tools, react roots, and HUD overlays alike.
+ * - {@link writeData} — EDITOR-TOOL plumbing: write a whole `.data.json`
+ *   back through the editor dev server, closing the live-tuning loop
+ *   (widget → file write → Vite HMR → `hotSwap` → {@link useData} re-render
+ *   → the running game reads the new value). Not for game code.
+ */
+import { useSyncExternalStore } from 'react';
+/**
+ * Read a data asset's current values and re-render whenever a hot edit lands
+ * (§3.3). A thin `useSyncExternalStore` over the handle's
+ * `subscribe`/`get` — any `defineData` handle works, no provider needed:
+ *
+ * ```tsx
+ * import { tuning } from '../data/tuning';
+ * const values = useData(tuning);   // fresh parsed object after every hotSwap
+ * ```
+ *
+ * `get()` returns the same reference between successful hot swaps, so this
+ * re-renders exactly once per accepted edit and never in between.
+ */
+export function useData(handle) {
+    return useSyncExternalStore((onStoreChange) => handle.subscribe(() => onStoreChange()), () => handle.get());
+}
+/**
+ * Write a data asset's ENTIRE new value back to its `.data.json` — the write
+ * half of a project tool's live-tuning loop (§3.3, D1: writes are file
+ * writes, always). POSTs to the editor dev server's `/__editor/data-file`
+ * route (see its doc comment in `packages/editor/server/editor-server.ts`),
+ * which accepts only `src/data/**\/*.data.json` and writes immediately; the
+ * running game then receives the change through the normal `.data.json` HMR
+ * path, exactly as if VS Code had saved the file.
+ *
+ * ```tsx
+ * // inside a tool's onChange — spread the live values, replace one field:
+ * void writeData('src/data/tuning.data.json', { ...tuning.get(), gravity: v });
+ * ```
+ *
+ * FOR TOOLS, NOT GAME CODE: data assets are immutable at runtime (§2.1) —
+ * runtime state belongs in your game's own store, never written back into
+ * data files. Outside a running editor there is no `/__editor` server, so
+ * this rejects with a teaching error (a shipped game could never reach the
+ * route anyway — builds strip `src/tools/` entirely, §4).
+ *
+ * Serialization matches the editor Data panel's diff-minimal contract:
+ * `"$schema"` first, 2-space indent, trailing newline. When `value` carries
+ * no `"$schema"` key (the common case — `DataHandle.get()` strips it), the
+ * conventional sibling reference (`./<name>.schema.json`, §2.1) is restored
+ * so a tool write never silently drops VS Code validation from the file.
+ */
+export async function writeData(projectRelativePath, value) {
+    if (!projectRelativePath.startsWith('src/data/') || !projectRelativePath.endsWith('.data.json')) {
+        throw new Error(`writeData: invalid path ${JSON.stringify(projectRelativePath)} — data assets live at ` +
+            'src/data/**/*.data.json, addressed project-relative, ' +
+            "e.g. writeData('src/data/tuning.data.json', next).");
+    }
+    // "$schema" first for minimal diffs; restore the conventional sibling
+    // reference when the caller's object (typically `{ ...handle.get() }`,
+    // which never carries it) omits the line.
+    const { $schema, ...rest } = value;
+    const schemaRef = $schema ??
+        `./${projectRelativePath
+            .split('/')
+            .pop()
+            ?.replace(/\.data\.json$/, '')}.schema.json`;
+    const content = `${JSON.stringify({ $schema: schemaRef, ...rest }, null, 2)}\n`;
+    const transactionalWriter = globalThis.__vgaiHistoryWriteData;
+    if (transactionalWriter) {
+        await transactionalWriter(projectRelativePath, content);
+        return;
+    }
+    let res;
+    try {
+        res = await fetch('/__editor/data-file', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ path: projectRelativePath, content }),
+        });
+    }
+    catch (err) {
+        throw new Error('writeData: could not reach the editor dev server (/__editor/data-file) — this helper is ' +
+            'editor-tool plumbing and only works inside the running ' +
+            'editor. Game code must not write data assets: they are immutable at runtime — ' +
+            `keep runtime state in your game's own store. (${String(err)})`);
+    }
+    if (!res.ok) {
+        const detail = await res.text().catch(() => '');
+        throw new Error(`writeData: the editor rejected the write to "${projectRelativePath}" ` +
+            `(HTTP ${res.status}${detail ? `: ${detail}` : ''}).`);
+    }
+}

package/dist/react/use-selection.d.ts

@@ -0,0 +1,54 @@
+/**
+ * W3.1 — `useSelection()`, the third tool-hooks contract member (alongside
+ * `useData`/`writeData` from `use-data.ts`). Where those two hooks are about
+ * DATA ASSETS, this one is about the currently-selected ENTITY.
+ *
+ * Scope, v1:
+ *  - INSPECTOR-placement tools only (`placement: 'inspector'`,
+ *    `define-tool.ts`). `EditorSelectionProvider` is host plumbing —
+ *    `InspectorToolSection` wraps every tool render in it; dock tools
+ *    (`ToolHost`/`BottomPanel`) have no adapter/selection in scope and never
+ *    get a provider. Calling `useSelection()` there throws a teaching error,
+ *    contained by the tool's `ToolErrorBoundary` (the editor survives).
+ *  - READ-only. Write through `InspectorProvider.set` / `writeData` (the
+ *    existing paths), never by mutating what this hook returns. Per-entity
+ *    WRITE-from-tool is deferred with `useTunable` (§10).
+ *
+ * Liveness — two existing paths reused, no new mechanism (§4's "reuse that
+ * path" rule):
+ *  1. Selection changes: `Inspector.tsx`'s own
+ *     `useSyncExternalStore(store.subscribe, store.getSnapshot)` re-renders
+ *     the panel, each matched `Section` gets the new `nodeId` prop, and
+ *     `InspectorToolSection` re-creates this provider's context value.
+ *  2. Edits while the SAME node stays selected: `adapter.subscribe` fires —
+ *     this hook keeps a local version counter bumped per notification
+ *     (exactly `game-state.tsx`'s `useRootObservation` pattern: the adapter
+ *     has no snapshot/version of its own, `subscribe` is fire-only) and
+ *     recomputes.
+ */
+import { type ReactNode } from 'react';
+import type { AuthoringAdapter, EditorNode } from '../adapter';
+/**
+ * EDITOR-side host plumbing: `InspectorToolSection` wraps a tool's rendered
+ * `<Component/>` in this, passing the adapter + nodeId it already holds.
+ * Project tools never render this themselves — it exists so `useSelection()`
+ * has something to read.
+ */
+export declare function EditorSelectionProvider({ adapter, nodeId, children, }: {
+    adapter: AuthoringAdapter;
+    nodeId: string | null;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export interface EditorSelection {
+    nodeId: string | null;
+    node: EditorNode | null;
+}
+/**
+ * The selected entity, live (read-only — see module doc).
+ *
+ * Throws outside an `EditorSelectionProvider` — inspector tools always render
+ * inside one; a dock tool or game-code caller does not, and the error names
+ * the fix rather than failing silently.
+ */
+export declare function useSelection(): EditorSelection;
+//# sourceMappingURL=use-selection.d.ts.map

package/dist/react/use-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-selection.d.ts","sourceRoot":"","sources":["../../src/react/use-selection.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAEL,KAAK,SAAS,EAKf,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAS/D;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,OAAO,EACP,MAAM,EACN,QAAQ,GACT,EAAE;IACD,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,SAAS,CAAC;CACrB,+BAGA;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,eAAe,CA8B9C"}

package/dist/react/use-selection.js

@@ -0,0 +1,71 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * W3.1 — `useSelection()`, the third tool-hooks contract member (alongside
+ * `useData`/`writeData` from `use-data.ts`). Where those two hooks are about
+ * DATA ASSETS, this one is about the currently-selected ENTITY.
+ *
+ * Scope, v1:
+ *  - INSPECTOR-placement tools only (`placement: 'inspector'`,
+ *    `define-tool.ts`). `EditorSelectionProvider` is host plumbing —
+ *    `InspectorToolSection` wraps every tool render in it; dock tools
+ *    (`ToolHost`/`BottomPanel`) have no adapter/selection in scope and never
+ *    get a provider. Calling `useSelection()` there throws a teaching error,
+ *    contained by the tool's `ToolErrorBoundary` (the editor survives).
+ *  - READ-only. Write through `InspectorProvider.set` / `writeData` (the
+ *    existing paths), never by mutating what this hook returns. Per-entity
+ *    WRITE-from-tool is deferred with `useTunable` (§10).
+ *
+ * Liveness — two existing paths reused, no new mechanism (§4's "reuse that
+ * path" rule):
+ *  1. Selection changes: `Inspector.tsx`'s own
+ *     `useSyncExternalStore(store.subscribe, store.getSnapshot)` re-renders
+ *     the panel, each matched `Section` gets the new `nodeId` prop, and
+ *     `InspectorToolSection` re-creates this provider's context value.
+ *  2. Edits while the SAME node stays selected: `adapter.subscribe` fires —
+ *     this hook keeps a local version counter bumped per notification
+ *     (exactly `game-state.tsx`'s `useRootObservation` pattern: the adapter
+ *     has no snapshot/version of its own, `subscribe` is fire-only) and
+ *     recomputes.
+ */
+import { createContext, useContext, useMemo, useRef, useSyncExternalStore, } from 'react';
+const SelectionContext = createContext(null);
+/**
+ * EDITOR-side host plumbing: `InspectorToolSection` wraps a tool's rendered
+ * `<Component/>` in this, passing the adapter + nodeId it already holds.
+ * Project tools never render this themselves — it exists so `useSelection()`
+ * has something to read.
+ */
+export function EditorSelectionProvider({ adapter, nodeId, children, }) {
+    const value = useMemo(() => ({ adapter, nodeId }), [adapter, nodeId]);
+    return _jsx(SelectionContext.Provider, { value: value, children: children });
+}
+/**
+ * The selected entity, live (read-only — see module doc).
+ *
+ * Throws outside an `EditorSelectionProvider` — inspector tools always render
+ * inside one; a dock tool or game-code caller does not, and the error names
+ * the fix rather than failing silently.
+ */
+export function useSelection() {
+    const ctx = useContext(SelectionContext);
+    if (!ctx) {
+        throw new Error('useSelection: no editor selection in context — this hook only works inside an editor-hosted ' +
+            "INSPECTOR tool (placement: 'inspector'). Dock tools and " +
+            'game code have no selection to read.');
+    }
+    const { adapter, nodeId } = ctx;
+    // Local version counter bumped per adapter notification — the adapter has
+    // no snapshot/version of its own, `subscribe` is fire-only (same pattern
+    // as `useRootObservation`'s `versionRef`, game-state.tsx).
+    const versionRef = useRef(0);
+    const version = useSyncExternalStore((onStoreChange) => adapter.subscribe?.(() => {
+        versionRef.current++;
+        onStoreChange();
+    }) ?? (() => { }), () => versionRef.current);
+    return useMemo(() => {
+        const node = nodeId ? adapter.hierarchy.node(nodeId) : null;
+        return { nodeId, node };
+        // `version` has no value of its own — only its CHANGE matters, as the
+        // liveness signal described above.
+    }, [adapter, nodeId, version]);
+}