@vgai/engine 0.3.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;
   };
 }
 
@@ -371,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/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,
@@ -80,4 +83,3 @@ export {
   type VgaiSceneConfig,
   VgaiSceneGameAdapter,
 } from './vgai-scene-game-adapter';
-export type { WorldKind } from './world-kind';

package/src/adapter/system-adapter.ts

@@ -133,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.
@@ -144,4 +216,5 @@ export interface SystemAdapters {
   assets?: AssetAdapter;
   navigation?: NavigationAdapter;
   audio?: AudioAdapter;
+  debug?: DebugAdapter;
 }