@vgai/engine 0.2.0

package/src/adapter/authoring.ts

@@ -0,0 +1,402 @@
+/**
+ * AuthoringAdapter — the editor's authoring contract. The editor talks to THIS,
+ * keyed by opaque string node ids, instead of to a concrete document format.
+ *
+ * `.vscn` / `SceneEntity` is the private model of ONE implementer
+ * (`VgaiSceneAuthoringAdapter`); an ingested game's adapter implements the same
+ * providers directly over its live `Object3D` tree. The editor sees only the
+ * interface and the advertised `capabilities` — it never branches on which
+ * implementer it is talking to.
+ *
+ * The interface lives in the engine (not the editor) so `MountedGame.authoring`
+ * can reference it without the engine depending on the editor; implementers live
+ * in `packages/editor/src/authoring/`.
+ *
+ * **Reserved inspector paths convention:** the property paths `name`, `visible`,
+ * and `locked` are reserved — an adapter that supports them exposes them through
+ * the ordinary `InspectorProvider.get`/`set` (no separate provider). The shell
+ * renders the hierarchy panel's rename field, eye (visibility) toggle, and lock
+ * toggle against these three paths, generically, for any adapter that reports
+ * them via `InspectorProvider.properties`.
+ */
+
+import type * as THREE from 'three';
+import type { SceneEntity } from '../scene/scene-types';
+import type { Transform, TransformOwner } from './transform';
+
+/** Booleans the editor UI gates affordances on (hide what an adapter can't do). */
+export interface AuthoringCapabilities {
+  transform: boolean;
+  material: boolean;
+  inspectorFields: boolean;
+  create: boolean;
+  delete: boolean;
+  reparent: boolean;
+  persist: boolean;
+  /**
+   * UI layout authoring (anchors/offsets/pivot/flex) — distinct from 3D
+   * `transform`. Optional so existing 3D adapters need not declare it. A UI
+   * adapter sets this true and implements {@link LayoutProvider}; the 3D gizmo /
+   * TransformProvider are NOT the UI manipulation path (spec K7).
+   */
+  layout?: boolean;
+}
+
+/** 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;
+  kind: 'mesh' | 'light' | 'camera' | 'group' | 'object' | (string & {});
+  parentId: string | null;
+  childIds: string[];
+  flags: {
+    runtimeOnly?: boolean;
+    locked?: boolean;
+    transformOwner?: TransformOwner;
+    /** D8 — member of a RootGroup, not the active one; children may be unloaded. */
+    inactiveRoot?: boolean;
+  };
+}
+
+export interface PropertyDescriptor {
+  path: string;
+  label: string;
+  type: 'string' | 'number' | 'boolean' | 'vec3' | 'color' | 'enum' | 'asset' | 'json';
+  readonly?: boolean;
+  options?: unknown[];
+  /**
+   * Optional domain-shaped grouping (T3.4 slice 2, docs/ADAPTER-AUTHORING-
+   * DESIGN.md §1.E): properties sharing the same `group` label render
+   * together under a titled sub-section in the generic inspector, instead of
+   * the flat property grid. Backward-compatible — omitted (or two
+   * descriptors with different/no `group`) renders exactly as before this
+   * field existed. This is the ONLY authoring-richness addition v1 makes;
+   * there is no schema and no new PropertyDescriptor `type` — a custom
+   * adapter reports its own domain concepts (health/score/an enum, …) through
+   * the SAME provider, merely labeled into a named group.
+   */
+  group?: string;
+}
+
+export interface HierarchyProvider {
+  roots(): EditorNode[];
+  node(id: string): EditorNode | null;
+  /** The live object for raycast/gizmo binding (null for non-object nodes). */
+  object3D(id: string): THREE.Object3D | null;
+  idForObject3D(o: THREE.Object3D): string | null;
+}
+
+export interface SelectionProvider {
+  get(): string[];
+  set(ids: string[]): void;
+}
+
+export interface TransformProvider {
+  get(id: string): Transform;
+  owner(id: string): TransformOwner;
+  /** Pause whatever controller fights the gizmo (physics/script) for editing. */
+  beginEdit(id: string): void;
+  apply(id: string, t: Transform): void;
+  endEdit(id: string): void;
+}
+
+export interface InspectorProvider {
+  /** Schema-driven — NOT fixed to `SceneEntity`. */
+  properties(id: string): PropertyDescriptor[];
+  get(id: string, path: string): unknown;
+  set(id: string, path: string, value: unknown): void;
+  /**
+   * Optional — REMOVE a property's authored override entirely (not "set to a
+   * value"), letting whatever governs it in its absence take over. The one
+   * concrete need today: a longhand CSS override (`style.borderTopLeftRadius`)
+   * that a uniform edit of its shorthand (`style.borderRadius`) must clear so
+   * the shorthand actually wins, instead of leaving a stale longhand that
+   * silently overrides it on reload (spec 27 §5 C2, U2). Adapters with no
+   * removable-override concept simply omit it — callers optional-chain.
+   */
+  remove?(id: string, path: string): void;
+}
+
+/**
+ * UI layout authoring (K7) — anchors/offsets/pivot/flex props on a UI node. This
+ * is the manipulation path for the DOM-overlay UI editor (handles, anchor presets,
+ * flex inspector) and is deliberately SEPARATE from {@link TransformProvider}
+ * (which is 3D position/quaternion/scale and cannot express flex/anchor layout).
+ * The layout shape is format-neutral (a plain object the UI adapter understands).
+ */
+export interface LayoutProvider {
+  /** The node's current layout object (anchors/offsets/pivot/flex), or null. */
+  get(id: string): Record<string, unknown> | null;
+  /** Pause whatever drives layout (animation) before a gesture, if needed. */
+  beginEdit(id: string): void;
+  /** Apply a (partial) layout patch — merged onto the node's layout. */
+  apply(id: string, layoutPatch: Record<string, unknown>): void;
+  /** Commit the gesture (one undo step). */
+  endEdit(id: string): void;
+}
+
+export interface StructureProvider {
+  create(kind: string, parentId?: string): string;
+  /**
+   * Remove `id`. May optionally return an awaitable (`Promise<void>`) when the
+   * underlying write is asynchronous (e.g. a react-world source-file edit) —
+   * `deleteSelection` (`editor-hotkeys.ts`) awaits it per id so a same-file
+   * multi-delete's writes land strictly one at a time (see that function's own
+   * doc comment for why serialization + deletion order together are what make
+   * a per-id loop sound for an adapter whose OID index isn't reindexed between
+   * writes). An adapter with a synchronous/in-memory remove (e.g.
+   * `UIAuthoringAdapter`) returns `void` — `await`ing it is a harmless no-op.
+   */
+  remove(id: string): void | Promise<void>;
+  duplicate(id: string): string;
+  reparent(id: string, newParentId: string | null): void;
+  /** Reorder `id` to sit immediately before `beforeSiblingId` among its siblings
+   *  (`null` = move to the end). Absent ⇒ the shell has no sibling-reorder UI
+   *  for this adapter. */
+  reorder?(id: string, beforeSiblingId: string | null): void;
+  /**
+   * The kinds `create` accepts for a given parent (`null` parentId = a new
+   * root), each with a display label — drives the shell's creation palette.
+   * Absent ⇒ the palette shows nothing for this adapter, even though `create`
+   * itself may still work when called directly (e.g. programmatically, or by
+   * an adapter-specific affordance outside the generic palette).
+   */
+  creatableKinds?(parentId: string | null): { kind: string; label: string }[];
+  /** D3 (spec 27 §6) — wrap `id` in a new container element (default tag
+   *  adapter-chosen, e.g. a `div`), re-parenting `id` as that container's sole
+   *  child. Absent ⇒ the shell's context menu shows no Wrap item for this
+   *  adapter. */
+  wrap?(id: string, wrapperTag?: string): void;
+  /** D3 (spec 27 §6) — replace `id` with its own children (the inverse of
+   *  `wrap`). Absent ⇒ the shell's context menu shows no Unwrap item for this
+   *  adapter. */
+  unwrap?(id: string): void;
+  /**
+   * D4.R2 (spec27 §6 D4 reopen) — remove every id in `ids` as ONE undoable
+   * op (a single Ctrl+Z restores the whole batch), instead of the caller
+   * looping `remove(id)` per id (which — one `remove` call = one undo push
+   * per adapter, by design — produces N separate undo entries: Ctrl+Z then
+   * restores them one at a time, asymmetric with the first-party adapter's
+   * own single batched multi-delete undo). Absent ⇒ the shell falls back to
+   * the per-id `remove` loop (today's N-entry behavior, unchanged) — an
+   * honest degrade, not a silent behavior change, for any adapter that
+   * hasn't implemented batching. May optionally return an awaitable
+   * (`Promise<void>`), same widening `remove` documents above and for the
+   * same reason (delete-order-residual fix): `deleteSelection`
+   * (`editor-hotkeys.ts`) awaits it so the caller can rely on the whole
+   * batch's write having landed before it returns. A synchronous/in-memory
+   * implementation (e.g. `UIAuthoringAdapter`'s) returns `void` — awaiting it
+   * is a harmless no-op.
+   */
+  removeMany?(ids: readonly string[]): void | Promise<void>;
+}
+
+/**
+ * PersistenceProvider — whether and where an adapter's edits persist (design:
+ * `docs/PERSISTENCE-PROVIDER-DESIGN.md` §2). The ACTIVE adapter's provider is the
+ * ONE place this is decided — the host (editor) never hard-codes a destination or
+ * guards on session flags; it asks the provider.
+ */
+export interface PersistenceProvider {
+  isDirty(): boolean;
+  /** Save to the adapter's OWN source of truth (.vscn / overlay file / …). */
+  save(): Promise<void>;
+  serialize(): unknown;
+  /** Migration aid (first-party direction): pull a subtree into `.vscn` entities. */
+  captureToVscn?(ids: string[]): SceneEntity[];
+  /**
+   * Human/agent-readable destination this provider persists to — e.g.
+   * `"scenes/main.vscn.json"`, `".vgai/overlays/fps.json"`, or `"ephemeral
+   * (discarded on stop)"`. Drives the save-status UI and makes routing
+   * inspectable (design §2). Implementers whose destination can change during
+   * the session (e.g. the first-party provider tracks the loaded `.vscn` path)
+   * should expose this as a live getter rather than a value captured once.
+   */
+  readonly destination: string;
+  /**
+   * The reload contract (design §5): apply an external change to this
+   * provider's persisted artifact into the RUNNING session (e.g. a file-watcher
+   * update to the `.vscn` or the overlay). Absent ⇒ the host must remount to
+   * pick up external changes (the honest floor). Implemented (T3.2 slice 3) by
+   * the first-party provider (`applyExternalUpdate`) and the ingest overlay
+   * provider (`applyOverlay`); absent (correctly) on the ephemeral provider.
+   *
+   * `rawContent`, when the host has it (the file-watcher SSE payload carries the
+   * artifact's exact bytes), is an OPTIONAL second parameter enabling own-echo
+   * detection — an event that is exactly what this provider itself last wrote is
+   * its own save reflected back, and should be skipped even outside the normal
+   * debounce window (see `EditorStore.applyExternalUpdate`'s doc comment). This
+   * stays optional/provider-specific — only the first-party provider currently
+   * uses it — so other implementers can ignore the parameter entirely.
+   */
+  applyExternal?(content: unknown, rawContent?: string): void;
+}
+
+/** D8 — mutually-exclusive root groups (radio roots): e.g. a "Scenes" group whose
+ *  members are the game's scene roots, only one of which is loaded/active at a
+ *  time (unlike ordinary sibling roots, which all coexist). */
+export interface RootGroup {
+  id: string; // stable, e.g. 'scenes'
+  label: string; // 'Scenes'
+  memberRootIds: string[]; // EditorNode ids; each is a hierarchy root
+  activeRootId: string | null;
+}
+export interface RootGroupsProvider {
+  groups(): RootGroup[];
+  activate(groupId: string, rootId: string): Promise<void> | void;
+}
+
+/** D8 — data-file → root mapping ("opening a file" = activating its root). */
+export interface FileMapProvider {
+  /** project-relative path → node id this adapter maps it to, else null. */
+  rootForFile(path: string): string | null;
+}
+
+/** D12 — per-layer viewport picking. Coordinates are client (browser) px. */
+export interface PickProvider {
+  pick(clientX: number, clientY: number): string | null;
+}
+
+/** D4 — storybook stories. */
+export interface StoryRef {
+  id: string;
+  label: string;
+}
+export interface StoriesProvider {
+  storiesFor(nodeId: string): StoryRef[]; // [] = none
+  active(nodeId: string): string | null;
+  apply(nodeId: string, storyId: string | null): void; // null clears
+  /** Render ONLY this node against the story (storybook canvas); null exits. */
+  isolate?(nodeId: string | null, storyId?: string): void;
+}
+
+/** D6 (S-C) — GameComponent management; config editing stays on InspectorProvider. */
+export interface ComponentsProvider {
+  available(nodeId: string): string[];
+  list(nodeId: string): { type: string }[];
+  add(nodeId: string, type: string): void;
+  remove(nodeId: string, type: string): void;
+}
+
+/** Asset drop (hierarchy + viewport). */
+export interface AssetDropProvider {
+  accepts(nodeId: string, assetPath: string): boolean;
+  drop(nodeId: string, assetPath: string): void;
+}
+
+/** Plain-object rect shape shared by {@link RectProvider} — the same fields a real
+ *  `DOMRect` carries (a subset, so a real `DOMRect` satisfies this structurally too).
+ *  See {@link RectProvider} for the coordinate space (host-relative, not viewport). */
+export interface DOMRectLike {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Per-node screen geometry — the KEYSTONE omission today (nothing produces rects the
+ *  ported inspect.ts math consumes). Coordinates are **host-relative** px: relative to
+ *  the adapter's own mounted world surface (its `position:absolute; inset:0` layer), the
+ *  same surface the A3 selection overlay is hosted over, so the overlay can draw against
+ *  these rects directly. (NOT viewport-client — the JSDoc formerly said so in error.) */
+export interface RectProvider {
+  /** selectable node id → its current bounding rect, or null if unmounted/offscreen */
+  rect(id: string): { x: number; y: number; width: number; height: number } | null;
+  /** rects of layout-relevant neighbours, for snap/measure/box-model overlays */
+  contextRects?(id: string): {
+    parent?: DOMRectLike;
+    siblings?: DOMRectLike[];
+    paddingBox?: DOMRectLike;
+  };
+  /**
+   * D3 (spec 27 §6) — every currently-empty container this adapter's tree
+   * contains right now: no visible children, no text, a collapsed dimension
+   * (the `ui-source/inspect.ts:findEmptyContainers` math) — each with a
+   * grown-to-tappable placeholder rect and a display name, driving the
+   * overlay's dashed empty-container hint. Host-relative, same coordinate
+   * space as {@link rect}. Absent ⇒ this adapter has no "empty container"
+   * concept (e.g. an adapter with no structural containers at all) — no
+   * hints are drawn for it.
+   */
+  emptyContainers?(): { id: string; rect: DOMRectLike; displayName: string }[];
+}
+
+/** Spatial gesture → source/data write, for non-Object3D (DOM) nodes. Distinct from the
+ *  3D TransformProvider. begin/apply/end bracket a single undo step; apply is live-preview. */
+export interface BoxEditProvider {
+  begin(id: string): void;
+  /** patch: any of x,y,width,height,marginTop… paddingLeft… — px deltas or absolutes */
+  apply(id: string, patch: Record<string, number>): void;
+  end(id: string): void;
+}
+
+/** Text-content editing — currently OFF-contract (the react adapter has an `editText(id)`
+ *  method, react-world-authoring-adapter.ts:728, not reachable via the contract). Bring it
+ *  on so the overlay's double-click-to-edit-text (D3) is contract-driven. */
+export interface TextProvider {
+  /** the element's editable pure-text, or null if the body is dynamic/has child elements */
+  get(id: string): string | null;
+  set(id: string, text: string): void; // dynamic-guarded by the writer
+}
+
+/**
+ * D3 (spec 27 §6) — background-color sampling at a viewport point, for the
+ * eyedropper's FALLBACK path (browsers with no native `EyeDropper` API). The
+ * native API, where available, samples real rendered pixels itself and needs
+ * none of this. Distinct from {@link PickProvider} (which returns a node id,
+ * not a color) and from `InspectorProvider.get('style.backgroundColor')`
+ * (which NORMALIZES to `#rrggbb` and so loses the "transparent" signal a
+ * color CHAIN walk needs — see `ui-source/inspect.ts:effectiveColorFromChain`'s
+ * doc comment: it walks raw, un-normalized CSS values looking for the first
+ * non-transparent one).
+ */
+export interface ColorSampleProvider {
+  /** Raw (un-normalized) CSS `background-color` values, hit-element FIRST,
+   *  walking up its ancestor chain — the exact shape
+   *  `effectiveColorFromChain` consumes. `null` when nothing is hit at the
+   *  point. Client (viewport) px, matching {@link PickProvider}. */
+  backgroundChainAt(clientX: number, clientY: number): string[] | null;
+}
+
+export interface AuthoringAdapter {
+  readonly capabilities: AuthoringCapabilities;
+  readonly hierarchy: HierarchyProvider; // required — minimum is "read the tree"
+  readonly selection?: SelectionProvider;
+  readonly transforms?: TransformProvider;
+  readonly inspector?: InspectorProvider;
+  /** UI layout authoring path (K7) — present on UI adapters, absent on 3D adapters. */
+  readonly layout?: LayoutProvider;
+  readonly structure?: StructureProvider;
+  readonly persistence?: PersistenceProvider;
+  /** D8 — mutually-exclusive root groups (radio roots). Absent ⇒ no grouped roots. */
+  readonly rootGroups?: RootGroupsProvider;
+  /** D8 — data-file → root mapping. Absent ⇒ this adapter maps no files to roots. */
+  readonly files?: FileMapProvider;
+  /** D12 — per-layer viewport picking. Absent ⇒ this adapter is not pickable. */
+  readonly pickable?: PickProvider;
+  /** T0 (spec 27 §2) — per-node screen geometry for a DOM visual editor's overlay/
+   *  snap/measure math. Absent ⇒ this adapter produces no rects (no overlay). */
+  readonly rects?: RectProvider;
+  /** T0 (spec 27 §2) — spatial drag-resize/move → source/data write for non-Object3D
+   *  (DOM) nodes. Absent ⇒ no box-edit gesture for this adapter. */
+  readonly boxEdit?: BoxEditProvider;
+  /** T0 (spec 27 §2) — double-click-to-edit-text on the contract (wires the react
+   *  adapter's existing off-contract `editText`). Absent ⇒ no in-place text edit. */
+  readonly text?: TextProvider;
+  /** D3 (spec 27 §6) — eyedropper fallback color sampling. Absent ⇒ the
+   *  canvas eyedropper swatch has no non-native path for this adapter. */
+  readonly colorSample?: ColorSampleProvider;
+  /** D4 — storybook stories. Absent ⇒ no stories for any node in this adapter. */
+  readonly stories?: StoriesProvider;
+  /** D6 (S-C) — GameComponent management. Absent ⇒ no component authoring. */
+  readonly components?: ComponentsProvider;
+  /** Asset drop (hierarchy + viewport). Absent ⇒ this adapter accepts no drops. */
+  readonly assetDrop?: AssetDropProvider;
+  /** Undo/redo for this adapter's edits (first-party delegates to the store; an
+   *  ingest adapter keeps its own overlay-backed stack). Absent ⇒ host falls back. */
+  undo?(): void;
+  redo?(): void;
+  /** Change notification → UI refresh. */
+  subscribe?(listener: () => void): () => void;
+}

package/src/adapter/colyseus-networking-adapter.ts

@@ -0,0 +1,72 @@
+/**
+ * ColyseusNetworkingAdapter — the first-party `NetworkingAdapter`. This is an
+ * INTROSPECTION / coordination boundary, NOT a transport: it lets the editor ask
+ * "is this object replicated, who owns it, may I edit it" — and, for the network
+ * inspector panel, "am I connected, to which room, how much replication activity
+ * is happening" — without owning Colyseus.
+ *
+ * It is parameterized by accessors over the room state (rather than a fixed schema)
+ * so any Colyseus room can supply one: map an `Object3D` to its network id + owner,
+ * report the local session and peers, and report connection/room/stats for the
+ * inspector. The editor uses `authority`/`editable` to keep remote/server-
+ * authoritative objects inspect-only (editing a replicated transform locally is
+ * meaningless — the server overwrites it next snapshot).
+ */
+
+import type * as THREE from 'three';
+import type {
+  ConnectionState,
+  NetPeer,
+  NetworkingAdapter,
+  ReplicationStats,
+  RoomInfo,
+  Unsubscribe,
+} from './system-adapter';
+
+export interface ColyseusNetworkingConfig {
+  /** The local peer's session id (objects it owns are editable). */
+  localSessionId(): string | null;
+  /** Peers currently in the room. */
+  peers(): NetPeer[];
+  /** Network id for an object, or null if it is not replicated (→ local authored). */
+  networkId(o: THREE.Object3D): string | null;
+  /** Owning peer/session id for a replicated object (null = server-owned). */
+  ownerId(o: THREE.Object3D): string | null;
+  /** True if the server is authoritative over this object (→ inspect-only). */
+  serverAuthoritative?(o: THREE.Object3D): boolean;
+  /** Current connection lifecycle state, for the network inspector panel.
+   *  Optional — defaults to `'disconnected'` for implementers that only need
+   *  object authority/editability (the pre-inspector config shape). */
+  connectionState?(): ConnectionState;
+  /** The active room's identity, or `null` when not connected to a room.
+   *  Optional — defaults to `null`. */
+  roomInfo?(): RoomInfo | null;
+  /** Replication activity snapshot (entity count + msg rates), for the inspector.
+   *  Optional — defaults to all-zero stats. */
+  replicationStats?(): ReplicationStats;
+  /** Subscribe to changes in connection state / room / replication stats.
+   *  Optional — defaults to a no-op subscription. */
+  subscribe?(cb: () => void): Unsubscribe;
+}
+
+export function createColyseusNetworkingAdapter(cfg: ColyseusNetworkingConfig): NetworkingAdapter {
+  return {
+    peers: () => cfg.peers(),
+    networkId: (o) => cfg.networkId(o),
+    authority: (o) => {
+      if (cfg.networkId(o) == null) return 'local'; // not replicated → local authored
+      if (cfg.serverAuthoritative?.(o)) return 'server';
+      return cfg.ownerId(o) === cfg.localSessionId() ? 'local' : 'remote';
+    },
+    editable: (o) => {
+      if (cfg.networkId(o) == null) return true; // local authored object
+      if (cfg.serverAuthoritative?.(o)) return false; // server owns it → inspect-only
+      return cfg.ownerId(o) === cfg.localSessionId(); // only your own peer's objects
+    },
+    getConnectionState: () => cfg.connectionState?.() ?? 'disconnected',
+    getRoomInfo: () => cfg.roomInfo?.() ?? null,
+    getReplicationStats: () =>
+      cfg.replicationStats?.() ?? { entities: 0, msgsInPerSec: 0, msgsOutPerSec: 0 },
+    subscribe: (cb) => cfg.subscribe?.(cb) ?? (() => {}),
+  };
+}

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

@@ -0,0 +1,103 @@
+/**
+ * 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
+ * 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.
+ */
+
+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,
+  AssetAdapter,
+  AudioAdapter,
+  InputAdapter,
+  NavigationAdapter,
+  NavPoint,
+} from './system-adapter';
+
+/** First-party `InputAdapter` over the engine `InputManager`. */
+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;
+      return out;
+    },
+  };
+}
+
+/** First-party `AssetAdapter` — resolves URLs through the engine loader (which
+ *  applies the project base + downloaded-asset remap). External/ingest games can
+ *  supply their own to redirect relative paths. */
+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()`
+ * (D10, T7.6) calls to silence a first-party world's audio. Restoring after a
+ * mute puts the gain back at whatever value it held right before muting (not
+ * a hardcoded `1`) — this composes correctly with an independent manual mute
+ * (the editor's `MuteButton`, `PlayBar.tsx`): pausing while already
+ * user-muted resumes muted, exactly as a user would expect.
+ */
+export function createAudioSystemAdapter(audio: GameAudio): AudioAdapter {
+  let muted = false;
+  let priorGain = audio.masterGain.gain.value;
+  return {
+    setMuted(next: boolean) {
+      if (next === muted) return;
+      muted = next;
+      if (next) {
+        priorGain = audio.masterGain.gain.value;
+        audio.masterGain.gain.value = 0;
+      } else {
+        audio.masterGain.gain.value = priorGain;
+      }
+    },
+    isMuted: () => muted,
+  };
+}
+
+/** First-party `NavigationAdapter` over the engine `NavMeshManager`. */
+export function createNavigationAdapter(nav: NavMeshManager): NavigationAdapter {
+  return {
+    hasNavMesh: () => nav.hasNavMesh(),
+    findPath: (start: NavPoint, end: NavPoint) => nav.findPath(start, end) as NavPoint[],
+    debugMesh: (scene: THREE.Scene) => nav.getDebugMesh(scene) as unknown as THREE.Object3D | null,
+  };
+}