@vgai/engine 0.2.0 → 0.3.0

package/dist/physics/trigger-dispatch.js

@@ -0,0 +1,80 @@
+/**
+ * Build a {@link CollisionHandler} that turns Rapier sensor overlaps into
+ * `onTriggerEnter` / `onTriggerExit` callbacks on the GameComponents of the two
+ * involved Object3Ds.
+ *
+ * Rapier collision events report collider *handles*; we resolve each to its
+ * Object3D via the physics registry's reverse index, then notify each side's
+ * components with the *other* Object3D. Only sensor-involved collisions dispatch
+ * triggers (a solid-vs-solid contact is a regular collision, not a trigger).
+ *
+ * Tracks currently-active trigger partners so that if one side is unregistered
+ * (despawned) from the physics registry before Rapier's own exit event is
+ * drained, the still-live side still gets its `onTriggerExit` (T1.12d) — see
+ * `physics.onRemove` below.
+ *
+ * Register with `collisions.onCollision(createTriggerDispatch(...))`.
+ */
+export function createTriggerDispatch(physics, components, rapierWorld, ctx) {
+    const activePartners = new Map();
+    const link = (a, b) => {
+        let set = activePartners.get(a);
+        if (!set) {
+            set = new Set();
+            activePartners.set(a, set);
+        }
+        set.add(b);
+    };
+    const unlink = (a, b) => {
+        const set = activePartners.get(a);
+        if (!set)
+            return;
+        set.delete(b);
+        if (set.size === 0)
+            activePartners.delete(a);
+    };
+    // Flush pending exits at unregister: an entity removed from the physics
+    // registry (e.g. despawned) may still have queued Rapier "stopped" events
+    // that never reach drain(), or may never generate one at all (the collider
+    // is simply gone). Either way, any object still tracked as its trigger
+    // partner must get its onTriggerExit now, not silently never.
+    physics.onRemove((object3D) => {
+        const partners = activePartners.get(object3D);
+        if (!partners || partners.size === 0)
+            return;
+        for (const other of partners) {
+            notify(components, other, object3D, false, ctx);
+            notify(components, object3D, other, false, ctx);
+            unlink(other, object3D);
+        }
+        activePartners.delete(object3D);
+    });
+    return (handleA, handleB, started) => {
+        const colA = rapierWorld.getCollider(handleA);
+        const colB = rapierWorld.getCollider(handleB);
+        if (!colA?.isSensor() && !colB?.isSensor())
+            return;
+        const objA = physics.getByColliderHandle(handleA);
+        const objB = physics.getByColliderHandle(handleB);
+        if (!objA || !objB)
+            return;
+        if (started) {
+            link(objA, objB);
+            link(objB, objA);
+        }
+        else {
+            unlink(objA, objB);
+            unlink(objB, objA);
+        }
+        notify(components, objA, objB, started, ctx);
+        notify(components, objB, objA, started, ctx);
+    };
+}
+function notify(components, self, other, started, ctx) {
+    for (const inst of components.getComponents(self)) {
+        if (started)
+            inst.onTriggerEnter?.(other, ctx);
+        else
+            inst.onTriggerExit?.(other, ctx);
+    }
+}

package/dist/react/game-state.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Engine-PUBLISHED `GameProvider`/`useGame`/`useGameState`/`useWorldObservation`
+ * (D-Z5, `docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md` §D-Z5) — the canonical,
+ * opt-in react entry for the T7.4 state bridge (`docs/REACT-STATE-BRIDGE.md`
+ * §3). This is a SEPARATE, react-value-importing module under
+ * `packages/engine/src/react/` — colocated per REACT-STATE-BRIDGE §3's own
+ * "colocate the react-facing hooks with the HUD seam, not the react-free
+ * core" rule, just now living IN the engine package rather than only in the
+ * project template. It is imported by NOTHING in the engine core import
+ * graph (`packages/engine/src/` outside this `react/` directory) — that
+ * invariant is proved by `packages/engine/test/react-core-import-ban.test.ts`
+ * (AC-F1).
+ *
+ * This module is the SPEC others port faithfully: it was originally authored
+ * as `packages/editor/template/src/ui/game-state.tsx` (T7.4); that file is
+ * now a thin re-export of this one (D-Z5 step 3) so every NEW scaffolded
+ * project gets ONE canonical context, while existing projects with their own
+ * full copy (their own `createContext`) keep working untouched — adoption of
+ * THIS module is an option, never a forced migration (D-Z5).
+ *
+ * Context-identity landmine (unchanged from the template file's own history,
+ * still the reason `loadProjectGameProvider`/the virtual-module plugin exist
+ * in `packages/editor/src/adapter-resolver.ts` /
+ * `packages/editor/vite-plugin-react-world-provider.ts`): `<GameProvider>`
+ * and `useGame()` must resolve against the SAME `createContext()` call. A
+ * project that ships its OWN `src/ui/game-state.tsx` (its own
+ * `createContext`) must be wrapped by ITS OWN `GameProvider` — wrapping it
+ * with THIS module's `GameProvider` instead would split context and
+ * `useGame()` would throw "no Game in context" even though a `<GameProvider>`
+ * genuinely wraps the tree (proved by
+ * `packages/editor/test/game-state-context-split.test.tsx`, AC-F1). This is
+ * exactly why the engine-published fallback (`resolveIngestReactAdapter`'s
+ * D-Y3 upgrade, `default-react`'s optional fallback) only ever fires when the
+ * project's OWN `src/ui/game-state.tsx` is ABSENT — an unmodified foreign
+ * entry that imports no vgai hooks has no context to split.
+ */
+import { type ReactNode } from 'react';
+import type { WorldStateObserver } from '../adapter';
+import { type Equals, shallow } from '../runtime/frame-selector-cache';
+import type { Game } from '../runtime/game';
+/** Re-exported for convenience — the opt-in equality for selectors that
+ *  return a fresh object/array/tuple every call (default is `Object.is`). */
+export { shallow };
+/** Provide the `Game` to `useGameState`/`useGame` for everything mounted
+ *  beneath it. Compose it around whatever renders your tree (`mountUI`, a
+ *  react world's `createRoot(...).render(...)`, etc.) — see the module doc
+ *  comment above for the context-identity rule this hook family depends on. */
+export declare function GameProvider({ game, children }: {
+    game: Game;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** Read the `Game` provided by the nearest `GameProvider`. Throws
+ *  descriptively when called outside one — matching the repo's loud-failure
+ *  habit rather than silently returning `null`. */
+export declare function useGame(): Game;
+/**
+ * Subscribe to a selected slice of game state (`docs/REACT-STATE-BRIDGE.md`
+ * §3). Re-renders only when the selected value changes: the selector re-runs
+ * at most once per completed frame (`game.state.frameVersion`), and
+ * `equals` (default `Object.is`; pass {@link shallow} for tuples/objects)
+ * gates whether the fresh result actually counts as a change.
+ *
+ * `selector` reads the live graph (e.g.
+ * `g => g.queryByComponent(Hp)[0]?.hp`) at post-frame quiescence — no
+ * copies. A selector that returns a fresh object every call must pass
+ * `shallow` (or an equivalent `equals`), or it will re-render every frame.
+ *
+ * Note: `equals` is captured once, when this hook first mounts (in the
+ * per-instance cache created below) — pass a stable function (module-level
+ * `shallow`/`Object.is`, or a value that doesn't change across renders),
+ * not a fresh inline arrow every render.
+ */
+export declare function useGameState<T>(selector: (game: Game) => T, equals?: Equals<T>): T;
+/**
+ * Pure, react-free lookup for the `useWorldObservation` hook below — factored
+ * out so the hook body stays a thin `useSyncExternalStore` wrapper. Throws
+ * descriptively (loud, not `undefined`-forever) when `worldId` doesn't name a
+ * registered world, or that world's mount has no `observe`
+ * (`WorldStateObserver`, `@engine/adapter`) — matching the `Game.registerWorld`
+ * "no state bridge" report (`runtime/game.ts`) this is the react-side half of.
+ */
+export declare function requireWorldObserver(game: Game, worldId: string): WorldStateObserver;
+/**
+ * Subscribe to a selected slice of a FOREIGN (non-first-party) world's
+ * observed state (`docs/REACT-STATE-BRIDGE.md` §4) — the ingested-world
+ * counterpart of `useGameState` above; both are sugar over the same
+ * subscribe/snapshot shape, so a react HUD reads native and ingested sources
+ * through one mental model.
+ *
+ * `selector` runs over that world's `snapshot()` — NOT the `Game` — since a
+ * foreign world hosts no `GameComponent`s to query. Re-renders only when the
+ * selected value changes (`equals`, default `Object.is`; pass {@link shallow}
+ * for tuples/objects returned fresh every call).
+ *
+ * Cadence note: unlike `useGameState`, this does NOT key its cache off
+ * `game.state.frameVersion` — a foreign/self-driven world may notify on its
+ * OWN rAF cadence, unrelated to our frame timing (§4's "consumers must not
+ * assume our frame timing"). Instead this keeps a local version counter,
+ * bumped once per `onChange` notification from the observer itself.
+ *
+ * Throws (loud, not a silently-undefined subscription) if `worldId` isn't
+ * registered, or its mount has no `observe` — see `requireWorldObserver`.
+ */
+export declare function useWorldObservation<T>(worldId: string, selector: (snapshot: unknown) => T, equals?: Equals<T>): T;
+//# sourceMappingURL=game-state.d.ts.map

package/dist/react/game-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-state.d.ts","sourceRoot":"","sources":["../../src/react/game-state.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAA4C,MAAM,OAAO,CAAC;AAChG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAA4B,KAAK,MAAM,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AACjG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;6EAC6E;AAC7E,OAAO,EAAE,OAAO,EAAE,CAAC;AAInB;;;+EAG+E;AAC/E,wBAAgB,YAAY,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,2CAEnF;AAED;;mDAEmD;AACnD,wBAAgB,OAAO,IAAI,IAAI,CAQ9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAAG,CAAC,CAW7F;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAiBpF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,CAAC,EAClC,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAC5B,CAAC,CAoBH"}

package/dist/react/game-state.js

@@ -0,0 +1,144 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Engine-PUBLISHED `GameProvider`/`useGame`/`useGameState`/`useWorldObservation`
+ * (D-Z5, `docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md` §D-Z5) — the canonical,
+ * opt-in react entry for the T7.4 state bridge (`docs/REACT-STATE-BRIDGE.md`
+ * §3). This is a SEPARATE, react-value-importing module under
+ * `packages/engine/src/react/` — colocated per REACT-STATE-BRIDGE §3's own
+ * "colocate the react-facing hooks with the HUD seam, not the react-free
+ * core" rule, just now living IN the engine package rather than only in the
+ * project template. It is imported by NOTHING in the engine core import
+ * graph (`packages/engine/src/` outside this `react/` directory) — that
+ * invariant is proved by `packages/engine/test/react-core-import-ban.test.ts`
+ * (AC-F1).
+ *
+ * This module is the SPEC others port faithfully: it was originally authored
+ * as `packages/editor/template/src/ui/game-state.tsx` (T7.4); that file is
+ * now a thin re-export of this one (D-Z5 step 3) so every NEW scaffolded
+ * project gets ONE canonical context, while existing projects with their own
+ * full copy (their own `createContext`) keep working untouched — adoption of
+ * THIS module is an option, never a forced migration (D-Z5).
+ *
+ * Context-identity landmine (unchanged from the template file's own history,
+ * still the reason `loadProjectGameProvider`/the virtual-module plugin exist
+ * in `packages/editor/src/adapter-resolver.ts` /
+ * `packages/editor/vite-plugin-react-world-provider.ts`): `<GameProvider>`
+ * and `useGame()` must resolve against the SAME `createContext()` call. A
+ * project that ships its OWN `src/ui/game-state.tsx` (its own
+ * `createContext`) must be wrapped by ITS OWN `GameProvider` — wrapping it
+ * with THIS module's `GameProvider` instead would split context and
+ * `useGame()` would throw "no Game in context" even though a `<GameProvider>`
+ * genuinely wraps the tree (proved by
+ * `packages/editor/test/game-state-context-split.test.tsx`, AC-F1). This is
+ * exactly why the engine-published fallback (`resolveIngestReactAdapter`'s
+ * D-Y3 upgrade, `default-react`'s optional fallback) only ever fires when the
+ * project's OWN `src/ui/game-state.tsx` is ABSENT — an unmodified foreign
+ * entry that imports no vgai hooks has no context to split.
+ */
+import { createContext, useContext, useRef, useSyncExternalStore } from 'react';
+import { createFrameSelectorCache, shallow } from '../runtime/frame-selector-cache';
+/** Re-exported for convenience — the opt-in equality for selectors that
+ *  return a fresh object/array/tuple every call (default is `Object.is`). */
+export { shallow };
+const GameContext = createContext(null);
+/** Provide the `Game` to `useGameState`/`useGame` for everything mounted
+ *  beneath it. Compose it around whatever renders your tree (`mountUI`, a
+ *  react world's `createRoot(...).render(...)`, etc.) — see the module doc
+ *  comment above for the context-identity rule this hook family depends on. */
+export function GameProvider({ game, children }) {
+    return _jsx(GameContext.Provider, { value: game, children: children });
+}
+/** Read the `Game` provided by the nearest `GameProvider`. Throws
+ *  descriptively when called outside one — matching the repo's loud-failure
+ *  habit rather than silently returning `null`. */
+export function useGame() {
+    const game = useContext(GameContext);
+    if (!game) {
+        throw new Error('useGame: no Game in context — wrap this component in <GameProvider game={ctx.game!}>.');
+    }
+    return game;
+}
+/**
+ * Subscribe to a selected slice of game state (`docs/REACT-STATE-BRIDGE.md`
+ * §3). Re-renders only when the selected value changes: the selector re-runs
+ * at most once per completed frame (`game.state.frameVersion`), and
+ * `equals` (default `Object.is`; pass {@link shallow} for tuples/objects)
+ * gates whether the fresh result actually counts as a change.
+ *
+ * `selector` reads the live graph (e.g.
+ * `g => g.queryByComponent(Hp)[0]?.hp`) at post-frame quiescence — no
+ * copies. A selector that returns a fresh object every call must pass
+ * `shallow` (or an equivalent `equals`), or it will re-render every frame.
+ *
+ * Note: `equals` is captured once, when this hook first mounts (in the
+ * per-instance cache created below) — pass a stable function (module-level
+ * `shallow`/`Object.is`, or a value that doesn't change across renders),
+ * not a fresh inline arrow every render.
+ */
+export function useGameState(selector, equals = Object.is) {
+    const game = useGame();
+    const cacheRef = useRef(null);
+    if (cacheRef.current === null) {
+        cacheRef.current = createFrameSelectorCache(equals);
+    }
+    return useSyncExternalStore((onStoreChange) => game.state.subscribe(onStoreChange), () => cacheRef.current.get(game.state.frameVersion, () => selector(game)));
+}
+/**
+ * Pure, react-free lookup for the `useWorldObservation` hook below — factored
+ * out so the hook body stays a thin `useSyncExternalStore` wrapper. Throws
+ * descriptively (loud, not `undefined`-forever) when `worldId` doesn't name a
+ * registered world, or that world's mount has no `observe`
+ * (`WorldStateObserver`, `@engine/adapter`) — matching the `Game.registerWorld`
+ * "no state bridge" report (`runtime/game.ts`) this is the react-side half of.
+ */
+export function requireWorldObserver(game, worldId) {
+    const world = game.world(worldId);
+    if (!world) {
+        throw new Error(`useWorldObservation: no world registered with id "${worldId}" — check game.worlds for the ` +
+            'ids actually registered.');
+    }
+    const observer = world.mounted.observe;
+    if (!observer) {
+        throw new Error(`useWorldObservation: world "${worldId}" (kind: ${world.kind}, adapter: "${world.adapter.id}") ` +
+            'has no state bridge — its mount has no `observe` (WorldStateObserver). This world cannot ' +
+            'be observed from React (docs/REACT-STATE-BRIDGE.md §4).');
+    }
+    return observer;
+}
+/**
+ * Subscribe to a selected slice of a FOREIGN (non-first-party) world's
+ * observed state (`docs/REACT-STATE-BRIDGE.md` §4) — the ingested-world
+ * counterpart of `useGameState` above; both are sugar over the same
+ * subscribe/snapshot shape, so a react HUD reads native and ingested sources
+ * through one mental model.
+ *
+ * `selector` runs over that world's `snapshot()` — NOT the `Game` — since a
+ * foreign world hosts no `GameComponent`s to query. Re-renders only when the
+ * selected value changes (`equals`, default `Object.is`; pass {@link shallow}
+ * for tuples/objects returned fresh every call).
+ *
+ * Cadence note: unlike `useGameState`, this does NOT key its cache off
+ * `game.state.frameVersion` — a foreign/self-driven world may notify on its
+ * OWN rAF cadence, unrelated to our frame timing (§4's "consumers must not
+ * assume our frame timing"). Instead this keeps a local version counter,
+ * bumped once per `onChange` notification from the observer itself.
+ *
+ * Throws (loud, not a silently-undefined subscription) if `worldId` isn't
+ * registered, or its mount has no `observe` — see `requireWorldObserver`.
+ */
+export function useWorldObservation(worldId, selector, equals = Object.is) {
+    const game = useGame();
+    const observer = requireWorldObserver(game, worldId);
+    const cacheRef = useRef(null);
+    if (cacheRef.current === null) {
+        cacheRef.current = createFrameSelectorCache(equals);
+    }
+    // Local notification-version counter — see the cadence note above. A
+    // plain mutable ref (not React state): bumping it must not itself trigger
+    // a render, `useSyncExternalStore`'s `onStoreChange` is what does that.
+    const versionRef = useRef(0);
+    return useSyncExternalStore((onStoreChange) => observer.subscribe(() => {
+        versionRef.current++;
+        onStoreChange();
+    }), () => cacheRef.current.get(versionRef.current, () => selector(observer.snapshot())));
+}

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

@@ -0,0 +1,60 @@
+/**
+ * React hooks for data assets — the tool-hooks half of
+ * `docs/DATA-TOOLS-DESIGN.md` §3.3, 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 worlds 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 worlds, 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,CA2Cf"}

package/dist/react/use-data.js

@@ -0,0 +1,96 @@
+/**
+ * React hooks for data assets — the tool-hooks half of
+ * `docs/DATA-TOOLS-DESIGN.md` §3.3, 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 worlds 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 worlds, 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 (docs/DATA-TOOLS-DESIGN.md §2.1), ' +
+            "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`;
+    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 (docs/DATA-TOOLS-DESIGN.md §3.3) and only works inside the running ' +
+            'editor. Game code must not write data assets: they are immutable at runtime (§2.1) — ' +
+            `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,75 @@
+/**
+ * W3.1 of docs/DATA-TOOLS-DESIGN.md §3.3 — `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 and the components authored on it —
+ * the gap a real consumer (`critter-types-w3b`'s `critter-type.tool.tsx`,
+ * §9.4) hit hard: with no way to read a component's own authored config, it
+ * had to recover species from `node.label` (a display string, not data).
+ *
+ * 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. `config` is a shallow copy of the authored record; write
+ *    through `InspectorProvider.set('components.<Type>.<field>', v)` /
+ *    `writeData` (the existing paths), never by mutating what this hook
+ *    returns. Per-entity WRITE-from-tool is deferred with `useTunable` (§10).
+ *  - Honest degrades, not errors, when the adapter is thinner than the vgai
+ *    first-party one: no `components` provider at all ⇒ `components: []`;
+ *    a `components` provider present but with no optional `config()`
+ *    accessor ⇒ each entry still appears (from `list()`) but with
+ *    `config: null`. Both mirror the `AuthoringAdapter` optional-provider
+ *    doctrine (§4) — an ingest/UI adapter that never implements `components`
+ *    was already legal, and stays legal.
+ *
+ * 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. Config edits while the SAME node stays selected: `adapter.subscribe`
+ *     fires (the vgai adapter's store notifies on every `updateEntity`,
+ *     which is what `InspectorProvider.set` goes through) — this hook keeps
+ *     a local version counter bumped per notification (exactly
+ *     `game-state.tsx`'s `useWorldObservation` 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-runtime").JSX.Element;
+/** One component attached to the selected entity, with its authored config
+ *  if the adapter can produce one (see the module doc's degrade rules). */
+export interface SelectedComponent {
+    type: string;
+    config: Record<string, unknown> | null;
+}
+export interface EditorSelection {
+    nodeId: string | null;
+    node: EditorNode | null;
+    components: SelectedComponent[];
+}
+/**
+ * The selected entity, live: its node, and every component attached to it
+ * with that component's own authored config (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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;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,2CAGA;AAED;2EAC2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,eAAe,CAmC9C"}