@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/adapter/{world-kind.ts → adapter-surface.ts}

@@ -1,26 +1,26 @@
 /**
- * `WorldKind` — the kinds of render surface a world can be (T7.1/T7.3/T6.2).
+ * `AdapterSurface` — the kinds of render surface a world can be (T7.1/T7.3/T6.2).
  *
  * Moved here (T7.5, `docs/BACKBONE-TASKS.md`'s D6 row) from `runtime/game.ts`
  * so `adapter/game-adapter.ts`'s kind-tagged `MountedWorld` types can name it
  * without a value-level import cycle (`runtime/game.ts` type-imports from
  * `adapter/game-adapter.ts` already). This is a leaf module — it imports
  * nothing — so anything may import it with zero risk of a cycle.
- * `runtime/game.ts` re-exports this SAME type (`export type { WorldKind }`),
- * so no existing `import type { WorldKind } from '../runtime/game'` call site
+ * `runtime/game.ts` re-exports this SAME type (`export type { AdapterSurface }`),
+ * so no existing `import type { AdapterSurface } from '../runtime/game'` call site
  * needed to change.
  */
-export type WorldKind = 'threejs' | 'pixijs' | 'react';
+export type AdapterSurface = 'threejs' | 'pixijs' | 'react';
 
 /**
- * Exhaustiveness guard for `WorldKind` dispatch (v4 architecture-review
+ * Exhaustiveness guard for `AdapterSurface` dispatch (v4 architecture-review
  * §7.4-2: a hypothetical 4th kind must fail to COMPILE at every kind-dispatch
  * site, not silently contribute nothing or silently default to an existing
  * kind). Lives here — colocated with the kind vocabulary itself, not in a
  * generic util module — so the three call sites that need it
  * (`runtime/create-runtime.ts`'s mount loop, `editor/adapter-resolver.ts`'s
  * `resolveAllWorlds`, `editor/play-mode.ts`'s `installMultiWorldAuthoring`)
- * import it from the same leaf module that defines `WorldKind`, keeping the
+ * import it from the same leaf module that defines `AdapterSurface`, keeping the
  * type and its guard from drifting apart. The `never` parameter is the
  * compile-time half of the guard (TS refuses to call this with anything the
  * compiler hasn't already narrowed to zero remaining variants); the thrown

package/src/adapter/authoring.ts

@@ -42,11 +42,68 @@ export interface AuthoringCapabilities {
   layout?: boolean;
 }
 
+/**
+ * The adapter's own answer to "what is truth behind these rows, and how
+ * writable is it" (spec 29 §5, docs/unified-world-editor/
+ * 29-hierarchy-philosophy.md). Provenance never varies WITHIN one adapter's
+ * rows — it is a property of the world boundary — so it is declared ONCE per
+ * adapter and rendered at the SEAM (the composite's `world:<id>` group row,
+ * or the panel header for a bare adapter), never per row. Only the adapter
+ * knows its truth: the shell must read this field, never guess from adapter
+ * identity (rule zero). Machine-readable operation gates stay in
+ * {@link AuthoringCapabilities}/provider presence — this type carries the
+ * HUMAN explanation those gates can point at when an affordance is present
+ * but unavailable.
+ */
+export interface AuthoringProvenance {
+  /**
+   * What the rows project:
+   * - `document` — an authored data file the editor owns (e.g. a scene file);
+   * - `source-code` — the game's own source is the document (e.g. JSX);
+   * - `foreign` — a live tree the editor does not own (an unmodified external
+   *   game, or any world edited only through an overlay); edits go to the
+   *   overlay, never the source;
+   * - `live` — a running game adopted at play time; edits are not persisted;
+   * - `boundary` — a declared world with no live editing surface here.
+   */
+  source: 'document' | 'source-code' | 'foreign' | 'live' | 'boundary';
+  /** Short badge text the shell shows verbatim at the seam (e.g. "scene",
+   *  "jsx", "overlay", "read-only", "live"). */
+  label: string;
+  /** One sentence explaining the truth/writability — shown as the seam
+   *  badge's tooltip and as the reason on disabled affordances. */
+  detail: string;
+}
+
+/**
+ * Semantic place a node occupies in the universal authoring hierarchy.
+ *
+ * `kind` below remains the adapter's native kind (`mesh`, `button`,
+ * `pixi-container`, ...). `role` says what the row MEANS to the editor shell,
+ * so presentation and interaction never have to infer semantics from an id,
+ * label, or substrate-specific kind string.
+ */
+export type EditorNodeRole =
+  | 'folder'
+  | 'root'
+  | 'document'
+  | 'story'
+  | 'component'
+  | 'element'
+  | 'entity'
+  | 'boundary';
+
 /** A node in the authoring hierarchy — format-neutral (not a `SceneEntity`). */
 export interface EditorNode {
   /** STABLE id — survives reload (see ingest structural-path ids). */
   id: string;
   label: string;
+  /** Adapter-declared semantic role. Optional for third-party/older adapters;
+   * the shell falls back to the native `kind` only for icon selection. */
+  role?: EditorNodeRole;
+  /** Optional source-owned context kept visually subordinate to `label`, such
+   * as `<header>` beneath a React component name or a document's file path. */
+  secondaryLabel?: string;
   kind: 'mesh' | 'light' | 'camera' | 'group' | 'object' | (string & {});
   parentId: string | null;
   childIds: string[];
@@ -56,6 +113,12 @@ export interface EditorNode {
     transformOwner?: TransformOwner;
     /** D8 — member of a RootGroup, not the active one; children may be unloaded. */
     inactiveRoot?: boolean;
+    /** Design state currently projected into the live authoring surface. */
+    active?: boolean;
+    /** The adapter resolved this boundary, but it is not editable here. */
+    readOnly?: boolean;
+    /** The adapter could not resolve the declared authoring boundary. */
+    error?: boolean;
   };
 }
 
@@ -277,6 +340,16 @@ export interface ComponentsProvider {
   list(nodeId: string): { type: string }[];
   add(nodeId: string, type: string): void;
   remove(nodeId: string, type: string): void;
+  /**
+   * OPTIONAL read accessor (W3.1, docs/DATA-TOOLS-DESIGN.md §3.3): the raw
+   * authored config record for one attached component (`list()` names the
+   * types; this reads one type's per-entity data), or `null` when the entity
+   * or component doesn't exist. Returns a shallow copy — callers must write
+   * through `InspectorProvider.set('components.<Type>.<field>', v)`, never by
+   * mutating this. Absent ⇒ config is not readable through this provider
+   * (tools degrade to `config: null`).
+   */
+  config?(nodeId: string, type: string): Record<string, unknown> | null;
 }
 
 /** Asset drop (hierarchy + viewport). */
@@ -361,6 +434,10 @@ export interface ColorSampleProvider {
 
 export interface AuthoringAdapter {
   readonly capabilities: AuthoringCapabilities;
+  /** Spec 29 §5 — seam-level provenance ("what is truth behind these rows").
+   *  Absent ⇒ the shell shows no provenance badge (degrade silently — never
+   *  fabricate a claim the adapter didn't make). */
+  readonly provenance?: AuthoringProvenance;
   readonly hierarchy: HierarchyProvider; // required — minimum is "read the tree"
   readonly selection?: SelectionProvider;
   readonly transforms?: TransformProvider;

package/src/adapter/first-party-systems.ts

@@ -1,20 +1,22 @@
 /**
  * First-party implementations of the remaining `SystemAdapters` — input, assets,
- * animation, navigation — each a thin coordination/introspection boundary over the
- * real engine subsystem (the original vision named these as first-class System
+ * navigation — each a thin coordination/introspection boundary over the real
+ * engine subsystem (the original vision named these as first-class System
  * adapters; physics + networking shipped earlier). The editor speaks only the
- * interfaces; these wrap `InputManager`, the asset loader, `AnimGraph`, and
- * `NavMeshManager` so an external game could supply its own equivalents.
+ * interfaces; these wrap `InputManager`, the asset loader, and `NavMeshManager`
+ * so an external game could supply its own equivalents. (The former
+ * `AnimationAdapter`/`createAnimationAdapter` over the `AnimGraph` map was
+ * removed by E5 — AnimGraph no longer exists; see
+ * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §3.3/§11 E5.)
  */
 
 import type * as THREE from 'three';
 import type { NavMeshManager } from '../ai/navigation';
-import type { AnimGraph } from '../animation/anim-graph';
 import type { InputManager } from '../input/input-manager';
 import { resolveUrl } from '../loader';
 import type { AudioContext as GameAudio } from '../setup/setup-audio';
 import type {
-  AnimationAdapter,
+  ActionValueSnapshot,
   AssetAdapter,
   AudioAdapter,
   InputAdapter,
@@ -22,13 +24,25 @@ import type {
   NavPoint,
 } from './system-adapter';
 
-/** First-party `InputAdapter` over the engine `InputManager`. */
+/** First-party `InputAdapter` over the engine `InputManager`. Reads each action through
+ *  `InputManager.readAction`, dispatched on that action's OWN declared `valueType`
+ *  (`getActionValueType`) — never a hardcoded getter — so a scalar/Vector2/pointer action
+ *  surfaces its real typed value instead of being coerced through `isPressed` (F1-followup;
+ *  `readAction` on the wrong type would throw, so dispatch must follow the declared type). */
 export function createInputManagerAdapter(input: InputManager): InputAdapter {
   return {
     poll: () => input.poll(),
     actions: () => {
-      const out: Record<string, number> = {};
-      for (const name of input.actionNames()) out[name] = input.isPressed(name) ? 1 : 0;
+      const out: Record<string, ActionValueSnapshot> = {};
+      for (const name of input.actionNames()) {
+        const type = input.getActionValueType(name);
+        // `readAction`'s return type is inferred from a literal `expectedType`; with `type`
+        // widened to `ActionValueType` here it collapses to `boolean | number | Vector2`, so
+        // digital's `boolean` is normalized to the adapter's 1/0 the same way the old digital-
+        // only adapter did — every other value type already reads as `number | Vector2`.
+        const raw = input.readAction(name, type);
+        out[name] = { type, value: typeof raw === 'boolean' ? (raw ? 1 : 0) : raw };
+      }
       return out;
     },
   };
@@ -41,31 +55,6 @@ export function createVgaiAssetAdapter(): AssetAdapter {
   return { resolve: (url) => resolveUrl(url) };
 }
 
-/** First-party `AnimationAdapter` over the runtime's `AnimGraph` map. */
-export function createAnimationAdapter(
-  animGraphs: Map<THREE.Object3D, AnimGraph>,
-): AnimationAdapter {
-  const paramsOf = (g: AnimGraph): Record<string, number | boolean> => {
-    const out: Record<string, number | boolean> = {};
-    for (const name of g.parameterNames()) {
-      const v = g.getParameter(name);
-      if (v !== undefined) out[name] = v;
-    }
-    return out;
-  };
-  return {
-    graphs: () =>
-      [...animGraphs.entries()].map(([object, g]) => ({
-        object,
-        state: g.getCurrentState(),
-        parameters: paramsOf(g),
-      })),
-    state: (o) => animGraphs.get(o)?.getCurrentState() ?? null,
-    getParameter: (o, name) => animGraphs.get(o)?.getParameter(name),
-    setParameter: (o, name, value) => animGraphs.get(o)?.setParameter(name, value),
-  };
-}
-
 /**
  * First-party `AudioAdapter` over the engine's master-gain bus
  * (`setup-audio.ts`'s `AudioContext.masterGain`) — the seam `Game.play.pause()`

package/src/adapter/game-adapter.ts

@@ -10,10 +10,10 @@
 
 import type { Container } from 'pixi.js';
 import type * as THREE from 'three';
+import type { AdapterSurface } from './adapter-surface';
 import type { AuthoringAdapter } from './authoring';
 import type { HostContext } from './host-context';
 import type { SystemAdapters } from './system-adapter';
-import type { WorldKind } from './world-kind';
 
 /**
  * The ingested-world observation contract (T7.4 slice 2 — `docs/
@@ -29,8 +29,8 @@ import type { WorldKind } from './world-kind';
 export interface WorldStateObserver {
   /**
    * Notified at most once per frame IF the adapter can hook the game's own
-   * update (`loop: 'gated'` worlds, `docs/CAPABILITY-TIERS.md` §(d));
-   * self-driven worlds (`loop: 'self-driven'`, raw-rAF) may notify on their
+   * update (`loop: 'gated'` roots, `docs/CAPABILITY-TIERS.md` §(d));
+   * self-driven roots (`loop: 'self-driven'`, raw-rAF) may notify on their
    * OWN rAF cadence instead — consumers must not assume our frame timing.
    * Returns an unsubscribe function.
    */
@@ -119,10 +119,10 @@ export interface MountedReactWorld extends MountedWorldBase {
  *  is typed against now, replacing the THREE-only `MountedGame`. */
 export type MountedWorld = MountedThreeWorld | MountedPixiWorld | MountedReactWorld;
 
-/** Map a {@link WorldKind} to its mounted-world shape (mirrors `NodeOf`/
+/** Map a {@link AdapterSurface} to its mounted-world shape (mirrors `NodeOf`/
  *  `BodyOf`/`ColliderOf` in `ecs/game-component.ts`) — lets generic code over
- *  `K extends WorldKind` name the right surface without a manual union. */
-export type MountedWorldFor<K extends WorldKind> = K extends 'threejs'
+ *  `K extends AdapterSurface` name the right surface without a manual union. */
+export type MountedWorldFor<K extends AdapterSurface> = K extends 'threejs'
   ? MountedThreeWorld
   : K extends 'pixijs'
     ? MountedPixiWorld
@@ -139,11 +139,11 @@ export type MountedWorldFor<K extends WorldKind> = K extends 'threejs'
 export type MountedGame = MountedThreeWorld;
 
 /** The interface every game implements to run on the host. Generic over
- *  {@link WorldKind} (T7.5) so a non-threejs implementer's `mount` returns its
+ *  {@link AdapterSurface} (T7.5) so a non-threejs implementer's `mount` returns its
  *  OWN kind-tagged surface instead of being cast through the threejs shape —
  *  defaults to `'threejs'` so every pre-T7.5 implementer/call site
  *  (`GameAdapter`, unparameterized) keeps compiling unchanged. */
-export interface GameAdapter<K extends WorldKind = 'threejs'> {
+export interface GameAdapter<K extends AdapterSurface = 'threejs'> {
   /** Stable id (telemetry/registry/conformance). */
   readonly id: string;
   /** Build/start the game against a host-provided context; return the handle. */

package/src/adapter/host-context.ts

@@ -4,7 +4,7 @@
  * This generalizes the old `GameContext`, which baked in first-party system
  * choices (a Rapier world, the postprocessing composer, the InputManager, …).
  * `HostContext` provides only what ANY game needs — the shared three instance, a
- * surface, a renderer, a loop, assets, a UI overlay — and lets a game *ask* for
+ * surface, a renderer, a loop, and assets — and lets a game *ask* for
  * a first-party subsystem via `requestSystem`, which the host may or may not
  * supply. The host never assumes Rapier/Colyseus; those live behind
  * `SystemAdapters` owned by the first-party implementer.
@@ -54,8 +54,6 @@ export interface HostContext {
   readonly loop: LoopHandle;
   /** Shared GLTF/texture cache. */
   readonly assets: AssetCache;
-  /** HUD overlay container (pointer-events:none by default). */
-  readonly ui: HTMLElement;
   /**
    * No GPU/DOM/audio available (Node conformance tests). A first-party adapter
    * skips postprocessing/render/audio/input-map loading but still builds the
@@ -68,7 +66,7 @@ export interface HostContext {
   /**
    * The Game root (T7.1 slice 1 — GAME-ROOT-DESIGN.md D6). The host
    * constructs the Game shell BEFORE mounting a `GameAdapter` and hands it
-   * down here so an adapter can expose `ctx.game`/`ctx.worlds` to the game it
+   * down here so an adapter can expose `ctx.game`/`ctx.roots` to the game it
    * mounts. Absent in headless harnesses and foreign hosts that predate the
    * Game root — everything must keep working when this is undefined (the
    * zero-break guarantee for this slice).

package/src/adapter/index.ts

@@ -10,15 +10,18 @@
  * docs/ADAPTER-ARCHITECTURE.md.
  */
 
+export type { AdapterSurface } from './adapter-surface';
 export type {
   AssetDropProvider,
   AuthoringAdapter,
   AuthoringCapabilities,
+  AuthoringProvenance,
   BoxEditProvider,
   ColorSampleProvider,
   ComponentsProvider,
   DOMRectLike,
   EditorNode,
+  EditorNodeRole,
   FileMapProvider,
   HierarchyProvider,
   InspectorProvider,
@@ -41,7 +44,6 @@ export {
   createColyseusNetworkingAdapter,
 } from './colyseus-networking-adapter';
 export {
-  createAnimationAdapter,
   createInputManagerAdapter,
   createNavigationAdapter,
   createVgaiAssetAdapter,
@@ -60,8 +62,7 @@ export type {
 export type { HostContext, HostSurface, LoopHandle, SystemRegistry } from './host-context';
 export { createRapierPhysicsAdapter } from './rapier-physics-adapter';
 export type {
-  AnimationAdapter,
-  AnimationGraphInfo,
+  ActionValueSnapshot,
   AssetAdapter,
   ConnectionState,
   InputAdapter,
@@ -82,4 +83,3 @@ export {
   type VgaiSceneConfig,
   VgaiSceneGameAdapter,
 } from './vgai-scene-game-adapter';
-export type { WorldKind } from './world-kind';

package/src/adapter/system-adapter.ts

@@ -12,6 +12,7 @@
  */
 
 import type * as THREE from 'three';
+import type { ActionValueType, Vector2 } from '../input/input-types';
 import type { Transform, TransformOwner } from './transform';
 
 /**
@@ -75,10 +76,22 @@ export interface NetworkingAdapter {
   subscribe(cb: () => void): Unsubscribe;
 }
 
+/** One action's current value, tagged with its declared shape (F1 `ActionValueType`) so a
+ *  consumer (editor input inspector, conformance suite) can render/assert on the real typed
+ *  value instead of a lossy digital coercion. `value` is a `number` for `'digital'`
+ *  (1 = pressed, 0 = not) and `'scalar'`, or a `Vector2` for `'vector2'`/`'pointerDelta'`/
+ *  `'pointerPosition'` — narrow on `type` to know which. */
+export interface ActionValueSnapshot {
+  type: ActionValueType;
+  value: number | Vector2;
+}
+
 export interface InputAdapter {
   poll(): void;
-  /** Current value of every named action (1 = pressed, 0 = not), for inspection. */
-  actions(): Readonly<Record<string, number>>;
+  /** Every named action's current value, faithfully typed per its declared `ActionValueType`
+   *  (F1, spec §12) — digital reads as 1/0, scalar as its float, vector2/pointerDelta/
+   *  pointerPosition as `{x,y}`. Never coerces a non-digital action down to 0/1. */
+  actions(): Readonly<Record<string, ActionValueSnapshot>>;
 }
 
 /** URL remap so an ingested game's relative asset paths resolve under the host. */
@@ -86,25 +99,6 @@ export interface AssetAdapter {
   resolve(url: string): string;
 }
 
-/** A snapshot of one object's animation graph (state + parameter values). */
-export interface AnimationGraphInfo {
-  object: THREE.Object3D;
-  state: string;
-  parameters: Record<string, number | boolean>;
-}
-
-/**
- * Inspect + drive a game's animation graphs (state machines / blend params). The
- * editor uses this to list animated objects, read their current state, and scrub
- * parameters — without owning the animation system.
- */
-export interface AnimationAdapter {
-  graphs(): AnimationGraphInfo[];
-  state(o: THREE.Object3D): string | null;
-  getParameter(o: THREE.Object3D, name: string): number | boolean | undefined;
-  setParameter(o: THREE.Object3D, name: string, value: number | boolean): void;
-}
-
 export interface NavPoint {
   x: number;
   y: number;
@@ -139,6 +133,78 @@ export interface AudioAdapter {
   isMuted(): boolean;
 }
 
+/** One tick-stamped debug event (`ctx.debug.emit`, spec §3.3): `tick`/`simT`
+ *  are the engine's own counters AT EMISSION, so events and state reads
+ *  correlate frame-exactly across every door (in-page bridge, relay, panels).
+ *
+ *  `seq` (run-4 friction #5 fix) is a registry-lifetime MONOTONIC counter,
+ *  strictly increasing by one per `emit()` call regardless of `tick` —
+ *  unlike `tick`, it is never shared by two events, which is what makes it
+ *  safe to fence on. A debug command handler runs BETWEEN ticks (its
+ *  emissions carry whatever `tick` is current at that instant, same as every
+ *  other emission at that instant would), so two DIFFERENT events — or an
+ *  event and a consumer's fence point — can legitimately share one `tick`;
+ *  `seq` never collides the same way, so "everything after what I've already
+ *  observed" is unambiguous. See `events(sinceTick, sinceSeq)` below. */
+export interface TickStampedEvent {
+  tick: number;
+  simT: number;
+  event: string;
+  detail?: unknown;
+  seq: number;
+}
+
+/** One registered debug command's listing shape — `locus` is always present
+ *  (defaults to `'client'` when a command didn't declare one) so every
+ *  listing surface can print it without a fallback of its own. */
+export interface DebugCommandInfo {
+  name: string;
+  description?: string | undefined;
+  /** JSON-Schema projection of the command's Zod args tuple, when declared. */
+  argsJsonSchema?: unknown;
+  locus: 'client' | 'server';
+}
+
+/**
+ * The debug/synthetic-player seam (`docs/SYNTHETIC-PLAYER-SPEC.md` §3.1):
+ * game-scoped introspection + actuation over whatever a game registers via
+ * `ctx.debug` (`registerStateProvider`/`registerCommand`/`emit`). NOT a
+ * gameplay API — this is the one seam the debug bridge, the editor's Debug
+ * Console/State Watch panels, and `@vgai/probe` all read/drive through.
+ */
+export interface DebugAdapter {
+  providers(): { name: string; tier: 'observable' | 'assisted' }[];
+  /** One provider's current value. Throws `DebugError` code
+   *  `STATE_PROVIDER_NOT_FOUND` (`data.registered`) for an unknown name. */
+  state(name: string): unknown;
+  /** One coherent snapshot of every registered provider — a throwing
+   *  provider contributes `{ __error: String(err) }` for its own key rather
+   *  than failing the whole snapshot. */
+  stateAll(): Record<string, unknown>;
+  commands(): DebugCommandInfo[];
+  /** Validates `args` against the command's declared Zod tuple (when
+   *  present), then awaits the registered fn. Throws `DebugError` code
+   *  `DEBUG_COMMAND_NOT_REGISTERED` for an unknown name,
+   *  `DEBUG_COMMAND_ARGS_INVALID` for a validation failure, or
+   *  `DEBUG_COMMAND_FAILED` wrapping anything the command itself threw. */
+  invoke(name: string, args: unknown[]): Promise<unknown>;
+  /** The tick-stamped event ring (cap 500, drops oldest).
+   *
+   *  - `sinceSeq` given (run-4 friction #5 fix): filters to `seq > sinceSeq`
+   *    — the unambiguous fence a consumer should use to mean "everything
+   *    emitted after what I've already observed" (see `TickStampedEvent.seq`'s
+   *    doc comment for why `tick` alone can't do this: a debug-command
+   *    emission and a consumer's fence point can share one tick, and the
+   *    old `tick > sinceTick` filter silently dropped same-tick events).
+   *    Takes precedence over `sinceTick` when both are given.
+   *  - `sinceTick` only: the ORIGINAL (pre-fix) filter, `tick > sinceTick` —
+   *    kept for back-compat callers that only ever had a tick to fence on;
+   *    still has the same-tick blind spot by construction, so a new caller
+   *    should prefer `sinceSeq`.
+   *  - Neither given: the whole ring. */
+  events(sinceTick?: number, sinceSeq?: number): TickStampedEvent[];
+}
+
 /**
  * The set of optional subsystem providers a mounted game may expose. Absence of
  * a provider means "capability not supported" — the editor degrades gracefully.
@@ -148,7 +214,7 @@ export interface SystemAdapters {
   networking?: NetworkingAdapter;
   input?: InputAdapter;
   assets?: AssetAdapter;
-  animation?: AnimationAdapter;
   navigation?: NavigationAdapter;
   audio?: AudioAdapter;
+  debug?: DebugAdapter;
 }