@vgai/editor 0.2.0

package/src/asset-events.ts

@@ -0,0 +1,100 @@
+import { watchSceneChanges } from './browser-watch-reload';
+import { connectEvents } from './editor-api';
+import { getEditorMode } from './editor-mode';
+
+export interface AssetMovedEvent {
+  oldPath: string;
+  newPath: string;
+  updatedFiles: string[];
+}
+
+export interface SceneChangedEvent {
+  path: string;
+  content: string;
+}
+
+/**
+ * Connect to the editor server's SSE endpoint for asset events.
+ * Returns a cleanup function to disconnect.
+ */
+export function connectAssetEvents(onAssetMoved: (event: AssetMovedEvent) => void): () => void {
+  // Browser mode (Phase A2): no Node dev server / SSE. A rename can't be
+  // reconstructed from self-derived watch events — a move surfaces as an
+  // unlinked `remove` + `create` with no old→new pairing — so asset-move sync
+  // stays a server-only signal (revisit with A4's external-change detection).
+  if (getEditorMode() === 'browser') {
+    void onAssetMoved;
+    return () => {};
+  }
+  const source = connectEvents();
+
+  source.addEventListener('asset-moved', (e: MessageEvent) => {
+    try {
+      const data = JSON.parse(e.data) as AssetMovedEvent;
+      onAssetMoved(data);
+    } catch {
+      /* ignore malformed events */
+    }
+  });
+
+  return () => source.close();
+}
+
+/**
+ * Connect to the editor server's SSE endpoint for scene file changes.
+ * Returns a cleanup function to disconnect.
+ */
+export function connectSceneEvents(onSceneChanged: (event: SceneChangedEvent) => void): () => void {
+  // Browser mode (Phase A2): no Node dev server / SSE. Derive scene-change
+  // events from the storage backend's own writes — the browser backend is the
+  // sole writer, so its self-derived events are the change signal (own-write
+  // echoes are suppressed downstream by the store's `_lastSavedContent` guard).
+  // See browser-watch-reload.ts.
+  if (getEditorMode() === 'browser') {
+    return watchSceneChanges(onSceneChanged);
+  }
+  const source = connectEvents();
+
+  source.addEventListener('scene-changed', (e: MessageEvent) => {
+    try {
+      const data = JSON.parse(e.data) as SceneChangedEvent;
+      onSceneChanged(data);
+    } catch {
+      /* ignore malformed events */
+    }
+  });
+
+  return () => source.close();
+}
+
+/**
+ * Connect to the editor server's SSE endpoint for project TOOL file
+ * add/unlink events (W6a, docs/DATA-TOOLS-DESIGN.md §7 W4 field note c). The
+ * server's `src/`-scoped watcher (`editor-server.ts`'s `startWatcher()`)
+ * broadcasts `tool-files-changed` whenever a `src/tools/*.tool.tsx` is added
+ * or removed; the event carries no payload of substance beyond the touched
+ * path — callers just re-run their own full rescan (`refreshProjectTools` is
+ * cheap by design, same physics as the D3 "discovery IS the folder scan"
+ * rule the DATA tab already follows).
+ */
+export function connectToolFileEvents(onChanged: () => void): () => void {
+  // Browser mode: no Node dev server / SSE — a project-src file add/remove
+  // can't be observed from the browser sandbox anyway (no filesystem watch).
+  if (getEditorMode() === 'browser') return () => {};
+  const source = connectEvents();
+  source.addEventListener('tool-files-changed', () => onChanged());
+  return () => source.close();
+}
+
+/**
+ * Connect to the editor server's SSE endpoint for project DATA file
+ * add/unlink events (W6a). Mirrors `connectToolFileEvents` for
+ * `src/data/*.data.json` / `*.schema.json` — the DATA tab's `refresh()` is
+ * the same rescan `active`-tab activation already triggers.
+ */
+export function connectDataFileEvents(onChanged: () => void): () => void {
+  if (getEditorMode() === 'browser') return () => {};
+  const source = connectEvents();
+  source.addEventListener('data-files-changed', () => onChanged());
+  return () => source.close();
+}

package/src/authoring/active-adapter.ts

@@ -0,0 +1,98 @@
+/**
+ * The editor's active {@link AuthoringAdapter} handle.
+ *
+ * The editor UI talks to the authoring contract through THIS accessor rather than
+ * reaching into `EditorStore` / `SceneEntity` directly. Today the only implementer
+ * is {@link VgaiSceneAuthoringAdapter} (first-party `.vscn`), so the accessor wraps
+ * the active store; when an ingested game is mounted (Phase B) the same accessor
+ * returns its `IngestAuthoringAdapter` and the UI code below it does not change.
+ *
+ * The adapter is a stateless delegating wrapper over the store, so we memoize one
+ * per store (a store's identity is stable for the editor session).
+ */
+
+import type { AuthoringAdapter } from '@engine/adapter';
+import type { EditorStore } from '../editor-store';
+import { VgaiSceneAuthoringAdapter } from './vgai-scene-authoring-adapter';
+
+const byStore = new WeakMap<EditorStore, AuthoringAdapter>();
+
+/**
+ * A non-first-party adapter (today: the ingest adapter for an unmodified game)
+ * that, while set, becomes the active authoring adapter. The editor renders its
+ * adapter-driven (format-neutral) hierarchy/inspector panels instead of the
+ * first-party `SceneEntity` panels while an override is active.
+ */
+let _override: AuthoringAdapter | null = null;
+
+/** Install/clear the active authoring override (ingest mode enters/exits). */
+export function setActiveAuthoring(adapter: AuthoringAdapter | null): void {
+  _override = adapter;
+}
+
+/** True when a non-first-party adapter is driving authoring (e.g. ingest). */
+export function hasAuthoringOverride(): boolean {
+  return _override !== null;
+}
+
+/**
+ * A1 — brand for the edit-mode composite (`edit-mode-authoring.ts`). Unlike an
+ * ingest/play override — a FOREIGN adapter whose document the store does not
+ * own — the edit-mode composite's FOCUSED child is the store's own first-party
+ * `VgaiSceneAuthoringAdapter` writing through the store's own save path. So
+ * the store's save guard (`_blockedForSave`) must NOT block it: an edit to the
+ * focused world must Ctrl+S/autosave to disk exactly like a single-scene
+ * project. The brand lives on the composite instance and disappears the moment
+ * `setActiveAuthoring(null)` clears the slot (the predicate checks the CURRENT
+ * `_override`'s identity), so no separate lifecycle state can go stale.
+ */
+const EDIT_MODE_BRAND = Symbol('vgai.editModeComposite');
+
+/** Mark `adapter` as the edit-mode composite (A1). */
+export function markEditModeOverride(adapter: AuthoringAdapter): void {
+  (adapter as unknown as Record<symbol, unknown>)[EDIT_MODE_BRAND] = true;
+}
+
+/** True when the ACTIVE override is the edit-mode composite (A1) — the store's
+ *  save guard allows the focused first-party child to persist through it. */
+export function activeOverrideIsEditMode(): boolean {
+  return (
+    _override !== null &&
+    (_override as unknown as Record<symbol, unknown>)[EDIT_MODE_BRAND] === true
+  );
+}
+
+/**
+ * Peek the raw override slot (or null) without a store handle — for a session
+ * that needs to install ITS OWN override while preserving whatever was active
+ * before it, so it can restore that exact value on exit instead of assuming
+ * null (e.g. play-mode's ephemeral-persistence wrapper, T3.2 slice 1).
+ */
+export function getAuthoringOverride(): AuthoringAdapter | null {
+  return _override;
+}
+
+/** Every node id in an adapter's hierarchy (for select-all over an ingested tree). */
+export function collectAllNodeIds(adapter: AuthoringAdapter): string[] {
+  const ids: string[] = [];
+  const walk = (node: { id: string; childIds: string[] }): void => {
+    ids.push(node.id);
+    for (const cid of node.childIds) {
+      const c = adapter.hierarchy.node(cid);
+      if (c) walk(c);
+    }
+  };
+  for (const r of adapter.hierarchy.roots()) walk(r);
+  return ids;
+}
+
+/** The authoring adapter the editor UI should drive for `store`. */
+export function getActiveAuthoring(store: EditorStore): AuthoringAdapter {
+  if (_override) return _override;
+  let a = byStore.get(store);
+  if (!a) {
+    a = new VgaiSceneAuthoringAdapter(store);
+    byStore.set(store, a);
+  }
+  return a;
+}

package/src/authoring/active-systems.ts

@@ -0,0 +1,50 @@
+/**
+ * Active system adapters the editor's authoring path coordinates with.
+ *
+ * A mounted game may expose `SystemAdapters` (physics / networking / …). The
+ * editor's gizmo-commit (through the `AuthoringAdapter.transforms` provider)
+ * consults THESE so it can:
+ *   - freeze a physics-owned body while the gizmo edits it, then commit the edited
+ *     pose to the body and resume (the founding doc's "frozen edit" mode —
+ *     generalizes the old `setEcsSyncTransform` teleport behind `PhysicsAdapter`);
+ *   - report a network-owned object's authority and keep remote/server-authoritative
+ *     objects inspect-only (`NetworkingAdapter`).
+ *
+ * Play-mode (first-party) installs the first-party `RapierPhysicsAdapter` /
+ * `ColyseusNetworkingAdapter` here on enter and clears them on exit; an ingested
+ * game would install its own. The editor never names Rapier/Colyseus — only the
+ * `PhysicsAdapter` / `NetworkingAdapter` interfaces.
+ */
+
+import type { SystemAdapters } from '@engine/adapter';
+
+let _systems: SystemAdapters = {};
+
+/** Install the active mounted game's System adapters (play-mode on enter). */
+export function setActiveSystems(systems: SystemAdapters | null): void {
+  _systems = systems ?? {};
+}
+/** The active System adapters (physics/networking/input/assets/animation/navigation). */
+export function getActiveSystems(): SystemAdapters {
+  return _systems;
+}
+
+export function setActivePhysics(p: SystemAdapters['physics'] | null): void {
+  const next = { ..._systems };
+  if (p) next.physics = p;
+  else delete next.physics;
+  _systems = next;
+}
+export function getActivePhysics(): SystemAdapters['physics'] | null {
+  return _systems.physics ?? null;
+}
+
+export function setActiveNetworking(n: SystemAdapters['networking'] | null): void {
+  const next = { ..._systems };
+  if (n) next.networking = n;
+  else delete next.networking;
+  _systems = next;
+}
+export function getActiveNetworking(): SystemAdapters['networking'] | null {
+  return _systems.networking ?? null;
+}

package/src/authoring/boundary-authoring-adapter.ts

@@ -0,0 +1,178 @@
+/**
+ * BoundaryAuthoringAdapter — A1's read-only {@link AuthoringAdapter} for a
+ * manifest-declared world that is NOT currently mounted (edit mode only runs
+ * the FOCUSED threejs world live — every other declared world is disclosed,
+ * not simulated; see `edit-mode-authoring.ts`'s doc comment for the seam this
+ * plugs into, and B1 for the "mount it live" upgrade path).
+ *
+ * A single node, one per world: label = the world id (or, for an unresolvable
+ * world, `⚠ <id> (unresolvable)` — #18, never a silent drop), `kind` = the
+ * manifest world kind, inspector exposes kind/adapter/entry-or-scene
+ * path/zOrder/pausable (+ `reason` when unresolvable) as READ-ONLY
+ * properties. No children, no live object, no structural/transform ops — this
+ * adapter's entire job is "say the world exists and why it isn't live yet".
+ *
+ * Resolvability is a CALLER decision (`edit-mode-authoring.ts` computes the
+ * reason from the manifest world entry) — this adapter just renders whatever
+ * reason string it's given; it never itself decides a world is broken.
+ */
+
+import type {
+  AuthoringAdapter,
+  AuthoringCapabilities,
+  EditorNode,
+  HierarchyProvider,
+  InspectorProvider,
+  PickProvider,
+  PropertyDescriptor,
+  SelectionProvider,
+} from '@engine/adapter';
+import type * as THREE from 'three';
+import type { EditorStore } from '../editor-store';
+
+/** The display-relevant slice of a manifest world entry — deliberately loose
+ *  (plain strings, not the engine's validated `WorldEntry['kind']` union) so
+ *  an UNRESOLVABLE world (unknown kind, e.g.) can still be described. */
+export interface BoundaryWorldInfo {
+  readonly id: string;
+  readonly kind: string;
+  /** Display string for the manifest's `adapter` field (e.g. `'default'`,
+   *  `'module:<path>'`) — omitted when not meaningfully derivable. */
+  readonly adapter?: string | undefined;
+  /** Whichever of `scene`/`entry` the world declares (display-only — this
+   *  adapter never reads the file). */
+  readonly entryOrScenePath?: string | undefined;
+  readonly zOrder: number;
+  readonly pausable: boolean;
+}
+
+const NO_CAPABILITIES: AuthoringCapabilities = {
+  transform: false,
+  material: false,
+  inspectorFields: false,
+  create: false,
+  delete: false,
+  reparent: false,
+  persist: false,
+};
+
+export class BoundaryAuthoringAdapter implements AuthoringAdapter {
+  readonly capabilities: AuthoringCapabilities = NO_CAPABILITIES;
+  private readonly world: BoundaryWorldInfo;
+  /** Non-null ⇒ error-node mode (#18) — set by the caller, never computed here. */
+  private readonly reason: string | null;
+  private readonly store: EditorStore;
+  /**
+   * D12 (B4) — a pixi design-time layer's stage hit-test, wired in by
+   * `design-time-layers.ts`'s `mountPixiLayer` success handler (a Boundary is
+   * still the pixi world's ONLY authoring adapter for the whole S-B effort —
+   * see this class's own doc comment — so its `pickable` rides on THIS
+   * adapter rather than a second pixi-specific one). Absent for every other
+   * Boundary (an unresolved/error world, or any non-pixi world) ⇒ this
+   * adapter reports no `pickable` at all, today's behavior. A plain
+   * conditionally-assigned field (not a getter always returning `{ pick:
+   * undefined }`) — this repo's `exactOptionalPropertyTypes` requires the key
+   * to be genuinely ABSENT, not present with an `undefined` value, to satisfy
+   * `AuthoringAdapter.pickable?: PickProvider`.
+   */
+  readonly pickable?: PickProvider;
+
+  constructor(
+    store: EditorStore,
+    world: BoundaryWorldInfo,
+    reason?: string,
+    pick?: PickProvider['pick'],
+  ) {
+    this.store = store;
+    this.world = world;
+    this.reason = reason ?? null;
+    if (pick) this.pickable = { pick };
+  }
+
+  private get label(): string {
+    return this.reason ? `⚠ ${this.world.id} (unresolvable)` : this.world.id;
+  }
+
+  private get node(): EditorNode {
+    return {
+      id: this.world.id,
+      label: this.label,
+      kind: this.world.kind,
+      parentId: null,
+      childIds: [],
+      flags: {},
+    };
+  }
+
+  readonly hierarchy: HierarchyProvider = {
+    roots: (): EditorNode[] => [this.node],
+    node: (id) => (id === this.world.id ? this.node : null),
+    object3D: (_id) => null,
+    idForObject3D: (_o: THREE.Object3D) => null,
+  };
+
+  /**
+   * Selection delegates to the editor-global {@link EditorStore} selection set
+   * — the SAME seam `IngestAuthoringAdapter`/`ReactWorldAuthoringAdapter` use
+   * (selection is editor UI state, not a per-adapter document concern). Without
+   * this, clicking a Boundary/error node in `IngestHierarchy` (the panel the
+   * composite drives) would be a silent no-op, so the node — and its `reason`
+   * (#18) — could never be selected or inspected (defect 3). It also makes the
+   * composite's empty-clear (`selection.set([])` routed to `children[0]`) work
+   * when a Boundary sorts first (defect 4).
+   */
+  readonly selection: SelectionProvider = {
+    get: () => [...this.store.selectedEntityIds],
+    set: (ids) => this.store.selectMultiple(ids),
+  };
+
+  readonly inspector: InspectorProvider = {
+    properties: (id): PropertyDescriptor[] => {
+      if (id !== this.world.id) return [];
+      const props: PropertyDescriptor[] = [
+        { path: 'kind', label: 'Kind', type: 'string', readonly: true },
+      ];
+      if (this.world.adapter !== undefined) {
+        props.push({ path: 'adapter', label: 'Adapter', type: 'string', readonly: true });
+      }
+      if (this.world.entryOrScenePath !== undefined) {
+        props.push({ path: 'path', label: 'Entry / Scene', type: 'string', readonly: true });
+      }
+      props.push(
+        { path: 'zOrder', label: 'Z Order', type: 'number', readonly: true },
+        { path: 'pausable', label: 'Pausable', type: 'boolean', readonly: true },
+      );
+      if (this.reason) {
+        props.push({ path: 'reason', label: 'Reason', type: 'string', readonly: true });
+      }
+      return props;
+    },
+    get: (id, path) => {
+      if (id !== this.world.id) return undefined;
+      switch (path) {
+        case 'kind':
+          return this.world.kind;
+        case 'adapter':
+          return this.world.adapter;
+        case 'path':
+          return this.world.entryOrScenePath;
+        case 'zOrder':
+          return this.world.zOrder;
+        case 'pausable':
+          return this.world.pausable;
+        case 'reason':
+          return this.reason ?? undefined;
+        default:
+          return undefined;
+      }
+    },
+    // Read-only — every property above is display-derived from the manifest;
+    // there is nowhere to persist a write to (matches how a not-yet-mounted
+    // world has no live document). No-op rather than throw, matching the
+    // reserved-paths convention's "adapters that don't support a path simply
+    // don't offer it" floor.
+    set: (_id, _path, _value) => {
+      // Intentionally inert.
+    },
+  };
+}