@volter/editor-game 0.5.65

package/src/ingest/unmount-ingest-root.ts

@@ -0,0 +1,224 @@
+/**
+ * Teardown for whatever `{ ingest }` root is live — the one path out of the
+ * session slot (`active-ingest.ts`), and the three per-surface dispose bodies
+ * it dispatches to.
+ *
+ * Every mount entry opens with {@link exitActiveIngest}, so this is also the
+ * cross-surface switch: mounting a canvas root over a live three root disposes
+ * the three session first, whichever surface it was.
+ *
+ * All three teardown bodies end at `reclaimGameRealm('')`. An ingested game
+ * runs in the DEFAULT `gated-globals.ts` realm, and these bodies used to reset
+ * its input gate to always-true and stop there — which left the dead game's
+ * window/document listeners attached to the real `window` AND ungated, for the
+ * rest of the tab's life, with the next ingest mount inheriting the list.
+ * Ending the realm is what releases them; it also drops the gate entry, so
+ * resetting the gate is no longer a separate step.
+ */
+
+import { setActiveAuthoring } from '@volter/editor-core/authoring/active-adapter';
+import { setActiveSystems } from '@volter/editor-core/authoring/active-systems';
+import { clearMountFailureReports } from '@volter/editor-core/authoring/mount-failure-report';
+import { editorConsole } from '@volter/editor-core/editor-console';
+import { reclaimGameRealm } from '../host/game-realm-reclaim';
+import { setGameRealmReloadHandler } from '../host/gated-globals';
+import {
+  activeIngest,
+  type IngestSession,
+  type IngestSession2D,
+  type IngestSessionReact,
+  setActiveIngest,
+} from './active-ingest';
+import { readIngestGameContract } from './game-contract-realm';
+import { clearIngestHook } from './ingest-evidence-hook';
+import { resetIngestPlaySurface } from './ingest-play-control';
+
+/**
+ * D-V1 slot collapse: tears down WHATEVER kind is currently active,
+ * dispatching to that kind's own teardown body ({@link disposeThreejsSession}/
+ * {@link disposePixiSession}/{@link disposeReactSession}) — the exact same
+ * per-kind dispose semantics as before the collapse (resizeObserver disconnect,
+ * `exitPlayScene`, mount/embed dispose, undo-adapter unregister,
+ * authoring/systems/mount-failure clears, canvas removal, react `stop()`),
+ * just no longer gated behind "is THIS kind the one currently active" — every
+ * mount entry guard calls this unconditionally, closing the cross-kind leak
+ * (F26 residual): switching kinds always disposes the prior session, whichever
+ * kind it was. {@link unmountThreeIngestRoot}/{@link unmountCanvasIngestRoot}/
+ * {@link unmountDomIngestRoot} become thin wrappers around this that only act
+ * when the slot holds their own kind — so a same-kind caller sees the exact
+ * same observable behavior as before the collapse.
+ *
+ * D-V2 (composite): a composite session's `siblings` (mounted by
+ * `ingest-siblings.ts`'s `mountIngestSiblings`, attached via
+ * `attachIngestSiblings`) tear down FIRST, in REVERSE mount order,
+ * before the primary session's own per-kind dispose body runs — every kind
+ * shares this ONE teardown path, so a sibling never outlives the ingest
+ * session it was mounted beside. A throwing sibling `dispose()` is caught
+ * individually (never blocks the rest of teardown) and logged loudly, never
+ * silently swallowed.
+ */
+export function exitActiveIngest(): void {
+  // The realm reload translation belongs to the session that just ended.
+  setGameRealmReloadHandler(null);
+  const active = activeIngest();
+  if (!active) return;
+  setActiveIngest(null);
+  resetIngestPlaySurface();
+  // THE GAME'S OWN WAY OUT RUNS FIRST. A contract-declared `lifecycle.dispose`
+  // is the one door that can end what the game's boot created — a self-booting
+  // R3F root's frame loop is not the host's to stop (see the contract slot's
+  // doc for the measured per-frame TypeError storm a dead mount's `useFrame`
+  // produced without it). Read before `reclaimGameRealm` ends the realm the
+  // contract lives in; declaration-gated, so a game that declares nothing
+  // (every canvas warm-remount game) is untouched.
+  try {
+    readIngestGameContract()?.lifecycle?.dispose?.();
+  } catch (err) {
+    editorConsole.error(`The game's own lifecycle.dispose threw at teardown: ${err}`, 'ingest');
+  }
+  for (let i = active.siblings.length - 1; i >= 0; i--) {
+    try {
+      active.siblings[i]!.dispose();
+    } catch (err) {
+      editorConsole.error(`Composite sibling dispose failed: ${err}`, 'ingest');
+    }
+  }
+  switch (active.kind) {
+    case 'three':
+      disposeThreejsSession(active.session);
+      return;
+    case 'canvas':
+      disposePixiSession(active.session);
+      return;
+    case 'dom':
+      disposeReactSession(active.session);
+      return;
+  }
+}
+
+/**
+ * D-V1: the three teardown body — byte-for-byte the pre-collapse
+ * `unmountThreeIngestRoot` logic below, extracted so {@link exitActiveIngest}
+ * can dispatch to it for ANY kind switch, not just a same-kind call.
+ * The slot and {@link resetIngestPlaySurface} are handled by the caller — this
+ * only does the threejs-specific teardown.
+ */
+function disposeThreejsSession(s: IngestSession): void {
+  // The concrete ingest adapter owns a session history resource. Dispose it
+  // when present; minimal/custom authoring implementations need no teardown.
+  if (s.mount?.authoring) {
+    s.mount.authoring.dispose?.();
+  }
+  setActiveAuthoring(null);
+  setActiveSystems(null);
+  clearMountFailureReports(); // D-W3: no session -> no mount failure left to report either
+  s.resizeObserver?.disconnect();
+  s.inputGateUnsubscribe?.();
+  if (s.mount) {
+    try {
+      s.store.exitPlayScene();
+    } catch {
+      /* scene may not have been swapped if capture failed */
+    }
+  }
+  s.store.setPlayState('stopped');
+
+  // Tear down the mounted game (stops its loop, frees renderer, uninstalls trap).
+  try {
+    s.mount?.game.dispose();
+  } catch {
+    /* ignore */
+  }
+
+  reclaimGameRealm('', 'The ingested game');
+  clearIngestHook('__vgaiIngest');
+  editorConsole.log('Ingest root unmounted', 'ingest');
+}
+
+/**
+ * D-V1: the pixi teardown body — byte-for-byte the pre-collapse
+ * {@link unmountCanvasIngestRoot} logic, extracted so {@link exitActiveIngest}
+ * can dispatch to it for ANY kind switch. The slot and
+ * {@link resetIngestPlaySurface} are handled by the caller — this only does the
+ * pixi-specific teardown.
+ */
+function disposePixiSession(s: IngestSession2D): void {
+  // v4 §7.1-13: the live canvas write target now self-registers with the undo
+  // timeline (mirrors `ThreeAuthoringAdapter` — see disposeThreejsSession's
+  // identical call above), so this session's entries must be dropped the same
+  // way on exit.
+  if (s.adapter) {
+    s.adapter.dispose();
+  }
+  setActiveAuthoring(null);
+  setActiveSystems(null);
+  clearMountFailureReports(); // D-W3: no session -> nothing left to report
+  s.store.setPlayState('stopped');
+  try {
+    s.dispose();
+  } catch {
+    /* ignore */
+  }
+  reclaimGameRealm('', 'The ingested canvas game');
+  clearIngestHook('__vgaiIngest2D');
+  editorConsole.log('canvas ingest root unmounted', 'ingest');
+}
+
+/**
+ * D-V1: the react teardown body — byte-for-byte the pre-collapse
+ * {@link unmountDomIngestRoot} logic, extracted so {@link exitActiveIngest} can
+ * dispatch to it for ANY kind switch. The slot and
+ * {@link resetIngestPlaySurface} are handled by the caller — this only does the
+ * react-specific teardown.
+ */
+function disposeReactSession(s: IngestSessionReact): void {
+  // Disposal expires its session history and releases listeners.
+  s.adapter.dispose();
+  setActiveAuthoring(null);
+  setActiveSystems(null);
+  clearMountFailureReports(); // D-W3: no session -> nothing left to report (mirrors disposeThreejsSession's identical call)
+  s.store.setPlayState('stopped');
+  try {
+    s.stop();
+  } catch {
+    /* ignore */
+  }
+  reclaimGameRealm('', 'The ingested DOM game');
+  clearIngestHook('__vgaiIngestReact');
+  editorConsole.log('DOM ingest root unmounted', 'ingest');
+}
+
+/**
+ * Unmount a three ingest root: restore the editor scene and tear down the game.
+ * D-V1: a thin wrapper that only acts when a three session is the one currently
+ * in the slot — same observable behavior as before the collapse (a no-op if
+ * nothing, or a DIFFERENT kind, is active); the actual teardown is
+ * {@link disposeThreejsSession} via {@link exitActiveIngest}.
+ */
+export function unmountThreeIngestRoot(): void {
+  if (activeIngest()?.kind !== 'three') return;
+  exitActiveIngest();
+}
+
+/**
+ * Unmount a canvas ingest root: tear down the captured game + adapter. D-V1: a
+ * thin wrapper that only acts when a canvas session is the one currently in the
+ * slot — same observable behavior as before the collapse; the actual teardown
+ * is {@link disposePixiSession} via {@link exitActiveIngest}.
+ */
+export function unmountCanvasIngestRoot(): void {
+  if (activeIngest()?.kind !== 'canvas') return;
+  exitActiveIngest();
+}
+
+/**
+ * Unmount a DOM (native-React) ingest root: unmount the react world + tear down
+ * its Game/loop. D-V1: a thin wrapper that only acts when a dom session is the
+ * one currently in the slot — same observable behavior as before the collapse;
+ * the actual teardown is {@link disposeReactSession} via
+ * {@link exitActiveIngest}.
+ */
+export function unmountDomIngestRoot(): void {
+  if (activeIngest()?.kind !== 'dom') return;
+  exitActiveIngest();
+}

package/src/navmesh/navmesh-actions.ts

@@ -0,0 +1,27 @@
+/**
+ * The window-event seam between the navmesh triggers (the Debug menu's
+ * Bake / Clear items, `contributions/navmesh.menu.ts`) and their listener
+ * (`navmesh-handler.ts`, started by `contributions/navmesh.service.ts`). Both
+ * sides import these names so a rename can never silently unwire the control —
+ * the handler would stop listening and the trigger would stop reaching it in
+ * the SAME edit.
+ *
+ * A window event (rather than a direct call) is deliberate: the handler follows
+ * the mounted `NavigationAdapter` and lives for the contribution pass, while
+ * the trigger is React menu chrome rendered on demand — the two never share a
+ * reference.
+ */
+
+export const NAVMESH_BAKE_EVENT = 'editor:bake-navmesh';
+export const NAVMESH_CLEAR_EVENT = 'editor:clear-navmesh';
+
+/** Ask the mounted game's navigation adapter to bake from the walkable-tagged
+ * meshes in the authoring scene. */
+export function dispatchNavMeshBake(): void {
+  window.dispatchEvent(new CustomEvent(NAVMESH_BAKE_EVENT));
+}
+
+/** Ask the mounted game's navigation adapter to clear its navmesh. */
+export function dispatchNavMeshClear(): void {
+  window.dispatchEvent(new CustomEvent(NAVMESH_CLEAR_EVENT));
+}

package/src/navmesh/navmesh-handler.ts

@@ -0,0 +1,237 @@
+import { getActiveSystems } from '@volter/editor-core/authoring/active-systems';
+import { editorHost } from '@volter/editor-sdk/host';
+import type { NavigationAdapter } from '@volter/editor-project/adapter';
+import { getUserData } from '@volter/threejs-runtime/ecs/user-data';
+import * as THREE from 'three';
+import { NAVMESH_BAKE_EVENT, NAVMESH_CLEAR_EVENT } from './navmesh-actions';
+import {
+  beginNavBake,
+  endNavBake,
+  markNavMeshBaked,
+  navBakeBusy,
+  resetNavMeshBaked,
+} from './navmesh-workflow-store';
+
+/**
+ * The game skew's side of the Navigation verbs: bake/clear and the walkable
+ * overlay tint, shown through the viewport door (`host.viewport.setHelper`,
+ * kind `navmesh` — the Helpers menu's own toggle).
+ *
+ * Started by `contributions/navmesh.service.ts`, so its lifetime is the
+ * contribution pass; it used to be a mount effect in the editor's scene panel,
+ * which made a host panel the owner of a game-skew tool.
+ *
+ * It reads the authoring scene through `host.hierarchy.objects()` and the
+ * viewport through `host.viewport.setHelper` / `.rig()`, but keeps the
+ * `@editor/authoring/active-systems` import for the adapter itself: the bake
+ * collects the PRIMARY AUTHORING mount's walkable meshes, so the adapter it
+ * bakes into must be that same mount's — `getActiveSystems()`. The door's
+ * `systems.inspected()` follows the INSPECTED instance (the Inspect selector),
+ * which in a split session is a different mount, and baking the authoring
+ * scene's geometry into another instance's navmesh is the bug that would
+ * cause. `host.systems.subscribe` IS `subscribeActiveNavigation` (measured in
+ * `editor-host-door.ts`), so only the read needs the direct import.
+ *
+ * This handler speaks ONLY to the mounted game's `NavigationAdapter`
+ * (bake/debug/clear). It never imports Recast, constructs a navigation
+ * implementation, or disposes its handles. Returns a dispose function for
+ * editor-owned listeners and presentation only.
+ */
+export function setupNavMeshHandlers(): () => void {
+  let boundNavigation: NavigationAdapter | null = null;
+
+  /** Unity-style blue walkable carpet (the helper's default is orange). */
+  const walkableMaterial = new THREE.MeshBasicMaterial({
+    color: 0x3b82f6,
+    transparent: true,
+    opacity: 0.5,
+    depthWrite: false,
+  });
+
+  function applyWalkableTint(helper: THREE.Object3D): void {
+    helper.traverse((child) => {
+      if ((child as THREE.Mesh).isMesh) (child as THREE.Mesh).material = walkableMaterial;
+    });
+  }
+
+  /**
+   * Nodes tagged for navmesh baking.
+   *
+   * The role is read from `userData['navRole']` — the format-neutral key
+   * `@volter/threejs-runtime/ecs/user-data` documents for exactly this ("navmesh role;
+   * collected at runtime"). An adapter-backed world tags its own objects.
+   */
+  function collectNavigationIds(role: 'walkable' | 'obstacle'): Set<string> {
+    const ids = new Set<string>();
+    for (const [id, obj] of editorHost().hierarchy.objects()) {
+      if (getUserData(obj, 'navRole') === role) ids.add(id);
+    }
+    return ids;
+  }
+
+  function clearPresentation(): void {
+    editorHost().viewport.setHelper('navmesh', null);
+  }
+
+  /** Follow late registration/replacement of the primary mounted adapter. A
+   * root may register navigation only after its async WASM setup completes. */
+  function syncMountedNavigation(): void {
+    const nav = getActiveSystems().navigation ?? null;
+    if (nav !== boundNavigation) {
+      boundNavigation = nav;
+      clearPresentation();
+    }
+    if (!nav) {
+      resetNavMeshBaked();
+      return;
+    }
+    let baked = false;
+    try {
+      baked = nav.hasNavMesh();
+    } catch (error) {
+      editorHost().console.error(
+        `Navigation adapter failed to report its state: ${error}`,
+        'navigation',
+      );
+    }
+    if (!baked) {
+      resetNavMeshBaked();
+      return;
+    }
+    markNavMeshBaked();
+    // The adapter builds its debug mesh against the editor's scene; without
+    // a mounted viewport there is nothing to show it in.
+    const scene = editorHost().viewport.rig()?.scene;
+    if (!scene) return;
+    let debugMesh: THREE.Object3D | null = null;
+    try {
+      debugMesh = nav.debugMesh(scene);
+    } catch (error) {
+      editorHost().console.error(
+        `Navigation adapter failed to create its debug mesh: ${error}`,
+        'navigation',
+      );
+    }
+    if (debugMesh) {
+      applyWalkableTint(debugMesh);
+      editorHost().viewport.setHelper('navmesh', debugMesh);
+    }
+  }
+
+  const onBake = async () => {
+    if (navBakeBusy()) return;
+    beginNavBake();
+    // Recast's solo bake is synchronous WASM — yield a frame so the Bake
+    // button visibly paints its busy state before the build blocks the thread.
+    await new Promise((r) => requestAnimationFrame(() => r(null)));
+    const nav = getActiveSystems().navigation;
+    if (!nav) {
+      const reason = 'The mounted game has no NavigationAdapter';
+      editorHost().console.warn(`${reason} — nothing can be baked`, 'navigation');
+      endNavBake(reason);
+      return;
+    }
+    if (!nav.bake) {
+      const reason = 'The mounted NavigationAdapter is inspect-only and does not support baking';
+      editorHost().console.warn(reason, 'navigation');
+      endNavBake(reason);
+      return;
+    }
+
+    const walkableIds = collectNavigationIds('walkable');
+    if (walkableIds.size === 0) {
+      editorHost().console.warn(
+        'No walkable entities found — tag meshes as "walkable" in the Navigation section',
+        'navigation',
+      );
+      endNavBake('No walkable-tagged entities in the scene');
+      return;
+    }
+
+    // Obstacle-role meshes go into the recast input TOO: recast's slope
+    // filter marks their steep faces unwalkable and erodes around them by
+    // walkableRadius — that is what carves holes the path routes around
+    // (Unity's Not-Walkable semantics). Only walkable-role presence gates
+    // the bake; obstacles alone can't produce a mesh.
+    const meshes: THREE.Mesh[] = [];
+    for (const id of [...walkableIds, ...collectNavigationIds('obstacle')]) {
+      const obj = editorHost().hierarchy.objects().get(id);
+      if (!obj) continue;
+      obj.traverse((child) => {
+        if ((child as THREE.Mesh).isMesh) meshes.push(child as THREE.Mesh);
+      });
+    }
+    if (meshes.length === 0) {
+      editorHost().console.error(
+        'NavMesh bake failed: the walkable-tagged entities have no meshes',
+        'navigation',
+      );
+      endNavBake('Walkable entities have no meshes');
+      return;
+    }
+
+    // Nothing authors bake parameters, so the bake uses recast's own defaults.
+    let success = false;
+    try {
+      success = nav.bake(meshes);
+    } catch (error) {
+      editorHost().console.error(`NavMesh bake failed: ${error}`, 'navigation');
+      endNavBake(`Bake failed: ${error}`);
+      return;
+    }
+    if (!success) {
+      editorHost().console.error('NavMesh bake failed', 'navigation');
+      endNavBake('Bake failed (recast rejected the input geometry)');
+      return;
+    }
+
+    boundNavigation = nav;
+    const scene = editorHost().viewport.rig()?.scene;
+    const debugMesh = scene ? nav.debugMesh(scene) : null;
+    if (debugMesh) {
+      applyWalkableTint(debugMesh);
+      editorHost().viewport.setHelper('navmesh', debugMesh);
+    }
+
+    endNavBake(null);
+
+    // The bake is SESSION-ONLY: no file is written and no loader reads one
+    // back, so the mesh lives only for as long as this editor session does.
+  };
+
+  const onClear = () => {
+    const nav = getActiveSystems().navigation;
+    if (!nav) {
+      editorHost().console.warn('The mounted game has no NavigationAdapter to clear', 'navigation');
+      return;
+    }
+    if (!nav.clear) {
+      editorHost().console.warn(
+        'The mounted NavigationAdapter is inspect-only and does not support clearing',
+        'navigation',
+      );
+      return;
+    }
+    try {
+      nav.clear(editorHost().viewport.rig()?.scene ?? new THREE.Scene());
+    } catch (error) {
+      editorHost().console.error(`NavMesh clear failed: ${error}`, 'navigation');
+      return;
+    }
+    clearPresentation();
+    resetNavMeshBaked();
+  };
+
+  window.addEventListener(NAVMESH_BAKE_EVENT, onBake);
+  window.addEventListener(NAVMESH_CLEAR_EVENT, onClear);
+  const unsubscribeNavigation = editorHost().systems.subscribe(syncMountedNavigation);
+  syncMountedNavigation();
+
+  return () => {
+    window.removeEventListener(NAVMESH_BAKE_EVENT, onBake);
+    window.removeEventListener(NAVMESH_CLEAR_EVENT, onClear);
+    unsubscribeNavigation();
+    clearPresentation();
+    walkableMaterial.dispose();
+  };
+}

package/src/navmesh/navmesh-workflow-store.ts

@@ -0,0 +1,78 @@
+/**
+ * The navmesh tool's OWN state: whether a session navmesh is baked and
+ * whether a bake is in flight.
+ *
+ * This is one tool's workflow state, and it lived in `EditorShellStore`
+ * alongside selection, the adoption stack and play state — where every one of
+ * its writes notified every subscriber in the editor, and the format-neutral
+ * store named a navmesh probe. The store holds what the whole shell shares; a
+ * tool holds its own, beside itself (`navmesh-handler.ts` is the tool).
+ *
+ * Module state, `useSyncExternalStore` shape (`subscribeNavWorkflow` +
+ * `navWorkflowVersion`) — the same shape `authoring/active-adapter.ts` uses.
+ */
+
+let _baked = false;
+/** Bake busy state (the Debug-menu items' honest progress gate: recast's solo
+ *  bake is synchronous WASM). */
+let _busy = false;
+const _listeners = new Set<() => void>();
+let _version = 0;
+
+function notify(): void {
+  _version++;
+  for (const listener of [..._listeners]) listener();
+}
+
+/** Subscribe to navmesh-workflow changes (`useSyncExternalStore` shape). */
+export function subscribeNavWorkflow(listener: () => void): () => void {
+  _listeners.add(listener);
+  return () => {
+    _listeners.delete(listener);
+  };
+}
+
+/** Monotonic version (`useSyncExternalStore` snapshot). */
+export function navWorkflowVersion(): number {
+  return _version;
+}
+
+/** `true` once a session navmesh has been baked (reset by Clear) — read by the
+ *  Debug menu's NavMesh items to reflect baked / not-baked. */
+export function navMeshBaked(): boolean {
+  return _baked;
+}
+
+export function markNavMeshBaked(): void {
+  if (_baked) return;
+  _baked = true;
+  notify();
+}
+
+/** Clear the baked flag — the Clear action removed the session mesh, so the
+ *  menu items must stop reading as "Baked". */
+export function resetNavMeshBaked(): void {
+  if (!_baked) return;
+  _baked = false;
+  notify();
+}
+
+export function navBakeBusy(): boolean {
+  return _busy;
+}
+
+/** Enter the baking busy state (the Debug-menu items disable on it). */
+export function beginNavBake(): void {
+  _busy = true;
+  notify();
+}
+
+/** Leave the busy state; `error === null` marks the bake successful. The error
+ *  TEXT is not stored — surfacing it loudly is the caller's job
+ *  (`navmesh-handler.ts` emits every failure to the editor console), and a
+ *  stored copy with no reader is what the schema-reader policy forbids. */
+export function endNavBake(error: string | null): void {
+  _busy = false;
+  if (error === null) _baked = true;
+  notify();
+}