@volter/editor-game 0.5.65

package/contributions/gameplay.command.ts

@@ -0,0 +1,255 @@
+/**
+ * The DEBUG-SEAM verbs of the session wire (`@volter/editor-sdk/commands`, a
+ * `workspace.command` contribution): reading a running game's declared state
+ * and commands, and actuating its input, time scale, seed and tick loop.
+ *
+ * All eight read/actuate the LIVE play session's game-scoped debug registry
+ * (`SystemAdapters.debug`, installed by `setActiveSystems` on play enter) or
+ * its InputManager/GameLoop (via `getPlayRuntimeAccess`). A stopped session
+ * answers with a structured failure, never a fabricated success; a running
+ * game that exposes NO debug adapter (a non-first-party mount) degrades to
+ * the honest empty/null shape.
+ *
+ * Play mode and the active-systems registry are the game skew's own modules,
+ * still housed in the editor until Play leaves the host (WORK.md §The
+ * workbench, G); they are reached through the `@editor/*` alias the editor's
+ * Vite serves to every contribution, and become this package's own imports
+ * when they move. Nothing here is host API.
+ */
+
+import { getActiveSystems } from '@volter/editor-core/authoring/active-systems';
+import type { CommandContribution } from '@volter/editor-sdk/commands';
+import { notPlayingResult, structuredErrorResult } from '../src/command-results';
+import { getPlayRuntimeAccess, isPlayModeActive } from '../src/play/play-mode';
+
+export const point = 'workspace.command';
+
+export const commands: CommandContribution['commands'] = {
+  'list-gameplay-state': {
+    derivedRefresh: 'if-content-changed',
+    handle: () => {
+      const debug = getActiveSystems().debug;
+      if (!debug) {
+        return isPlayModeActive() ? { ok: true, data: { providers: [] } } : notPlayingResult();
+      }
+      return { ok: true, data: { providers: debug.providers() } };
+    },
+  },
+  'inspect-gameplay-state': {
+    derivedRefresh: 'if-content-changed',
+    handle: (cmd) => {
+      const debug = getActiveSystems().debug;
+      if (!debug) {
+        return isPlayModeActive() ? { ok: true, data: { state: null } } : notPlayingResult();
+      }
+      const keys = cmd['keys'] as string[] | undefined;
+      try {
+        const state: Record<string, unknown> = {};
+        if (keys && keys.length > 0) {
+          for (const key of keys) state[key] = debug.state(key);
+        } else {
+          Object.assign(state, debug.stateAll());
+        }
+        return { ok: true, data: { state } };
+      } catch (err) {
+        return structuredErrorResult(err);
+      }
+    },
+  },
+  'list-debug-commands': {
+    derivedRefresh: 'if-content-changed',
+    handle: () => {
+      const debug = getActiveSystems().debug;
+      if (!debug) {
+        return isPlayModeActive() ? { ok: true, data: { commands: [] } } : notPlayingResult();
+      }
+      return { ok: true, data: { commands: debug.commands() } };
+    },
+  },
+  'invoke-debug-command': {
+    derivedRefresh: 'always',
+    handle: async (cmd) => {
+      const debug = getActiveSystems().debug;
+      if (!debug) {
+        if (!isPlayModeActive()) return notPlayingResult();
+        // Honest not-registered shape: no adapter means NOTHING is registered.
+        return {
+          ok: false,
+          error: `debug: no command registered under "${cmd['name']}" — this game exposes no debug adapter`,
+          data: { code: 'DEBUG_COMMAND_NOT_REGISTERED', registered: [] },
+        };
+      }
+      try {
+        const result = await debug.invoke(cmd['name'] as string, (cmd['args'] as unknown[]) ?? []);
+        return { ok: true, data: { result } };
+      } catch (err) {
+        return structuredErrorResult(err);
+      }
+    },
+  },
+  'inject-input': {
+    derivedRefresh: 'none',
+    handle: (cmd) => {
+      const runtime = getPlayRuntimeAccess();
+      if (!runtime) {
+        return { ok: false, error: 'not in play mode — start play before injecting input' };
+      }
+      // D15/T-D15.5 (review objection 2's fix) — resolved through the SAME
+      // per-world `DebugRegistry.getVirtualInputTarget(worldId?)` the debug
+      // bridge's `window.__vgai.input.*` calls, instead of the old
+      // `Game.input` (always the DEFAULT world only) — an explicit
+      // `cmd['worldId']` reaches that world specifically; omitted resolves
+      // to the same default both doors now share. Throws
+      // `DEBUG_INPUT_WORLD_NOT_FOUND` (caught below) for an explicit,
+      // unregistered world id.
+      let input: ReturnType<typeof runtime.getInputTarget>;
+      try {
+        input = runtime.getInputTarget(cmd['worldId'] as string | undefined);
+      } catch (err) {
+        return structuredErrorResult(err);
+      }
+      if (!input) {
+        return {
+          ok: false,
+          error: 'this play session has no first-party InputManager to inject into',
+        };
+      }
+      try {
+        // Action-level is primary (frozen decision, spec §3.2): the honest
+        // gated path — a gated actuation surfaces {delivered:false, reason},
+        // never a false ok. The four legacy kinds map to the persistent
+        // test-source injectors (read back only through declared test_*
+        // bindings, so `delivered` here means "the source was written").
+        if (cmd['kind'] === 'action') {
+          const atTick = cmd['atTick'];
+          // D15/T-D15.5 — `atTick` defers to InputManager.scheduleActionAtTick
+          // instead of an immediate setVirtualAction. scheduleActionAtTick
+          // throws InputActionError/a valueType mismatch (same as
+          // setVirtualAction) or InputTickError ('TICK_ALREADY_PASSED',
+          // data.currentTick) — all caught by this handler's outer try/catch
+          // below via structuredErrorResult.
+          if (typeof atTick === 'number') {
+            input.scheduleActionAtTick(
+              atTick,
+              cmd['action'] as string,
+              cmd['value'] as boolean | number | { x: number; y: number },
+            );
+            return { ok: true, data: { scheduled: true, tick: atTick } };
+          }
+          const outcome = input.setVirtualAction(
+            cmd['action'] as string,
+            cmd['value'] as boolean | number | { x: number; y: number },
+          );
+          return { ok: true, data: outcome };
+        }
+        const sourceId = cmd['sourceId'] as string;
+        switch (cmd['kind']) {
+          case 'axis':
+            input.injectAxis(sourceId, cmd['value'] as number);
+            break;
+          case 'vector2':
+            input.injectVector2(sourceId, cmd['value'] as { x: number; y: number });
+            break;
+          case 'pointerDelta':
+            input.injectPointerDelta(sourceId, cmd['value'] as { x: number; y: number });
+            break;
+          case 'pointerPosition':
+            input.injectPointerPosition(sourceId, cmd['value'] as { x: number; y: number });
+            break;
+          default:
+            return { ok: false, error: `unknown injection kind "${cmd['kind']}"` };
+        }
+        return { ok: true, data: { delivered: true } };
+      } catch (err) {
+        return structuredErrorResult(err);
+      }
+    },
+  },
+  'set-time-scale': {
+    derivedRefresh: 'none',
+    handle: (cmd) => {
+      const runtime = getPlayRuntimeAccess();
+      if (!runtime) {
+        return { ok: false, error: 'not in play mode — start play before setting time-scale' };
+      }
+      runtime.loop.timeScale = cmd['timeScale'] as number;
+      // Read back after the loop's own [0,8] clamp so the caller sees the
+      // value actually applied.
+      return { ok: true, data: { timeScale: runtime.loop.timeScale } };
+    },
+  },
+  // D15/T-D15.6 — the `play.seed.set` relay verb: reaches the live
+  // session's `ctx.random.reseed(seed)` through `getPlayRuntimeAccess()`'s
+  // `random` accessor. Gated on `determinismDeclared` (the running
+  // project's manifest `determinism.seededRandom`, per T4.1: reseeding a
+  // project with no documented determinism contract would silently imply
+  // one exists) — the structured `DETERMINISM_NOT_DECLARED` marker the SDK
+  // maps to its own declared error code.
+  'set-seed': {
+    derivedRefresh: 'none',
+    handle: (cmd) => {
+      const runtime = getPlayRuntimeAccess();
+      if (!runtime) {
+        return { ok: false, error: 'not in play mode — start play before setting the seed' };
+      }
+      if (!runtime.determinismDeclared) {
+        return {
+          ok: false,
+          error:
+            "this project's manifest does not declare determinism.seededRandom — " +
+            'play.seed.set has no documented contract to reseed against (D15)',
+          data: { code: 'DETERMINISM_NOT_DECLARED' },
+        };
+      }
+      if (!runtime.random) {
+        return {
+          ok: false,
+          error: 'this play session has no first-party ctx.random to reseed',
+        };
+      }
+      runtime.random.reseed(cmd['seed'] as number);
+      // Read back the live, post-reseed value (mirrors set-time-scale's own
+      // read-after-apply convention immediately above).
+      return { ok: true, data: { seed: runtime.random.seed } };
+    },
+  },
+  // D15/T-D15.4 — the `play.runTicks` relay verb: reaches the live
+  // session's `GameInternal.runTicks` through `getPlayRuntimeAccess()`'s
+  // `runTicks` accessor (itself backed by the SAME
+  // `DebugRegistry.getRunTicksTarget()` the bridge's
+  // `window.__vgai.runTicks` calls — one implementation, byte-identical
+  // behavior across doors, D17). `runTicks` itself throws a structured
+  // `DebugError` (`RUN_TICKS_PAUSED`) while paused — never a silent no-op —
+  // which `structuredErrorResult` below carries through as `data.code`.
+  'run-ticks': {
+    derivedRefresh: 'none',
+    handle: async (cmd) => {
+      const runtime = getPlayRuntimeAccess();
+      if (!runtime) {
+        return { ok: false, error: 'not in play mode — start play before running ticks' };
+      }
+      if (!runtime.runTicks) {
+        return {
+          ok: false,
+          error: 'this play session has no first-party Game to run ticks on',
+          data: { code: 'RUN_TICKS_UNAVAILABLE' },
+        };
+      }
+      try {
+        const n = cmd['n'] as number;
+        const render = cmd['render'] as 'last' | 'all' | 'none' | undefined;
+        // The settled-aware driver (`runtime/run-ticks-settled.ts`): a tick never races a
+        // scene remount's async commit — byte-identical with the bridge's `runTicksSettled`
+        // door (D17). With no world-settled probe registered it is `runTicks` exactly.
+        if (runtime.runTicksSettled) {
+          await runtime.runTicksSettled(n, render ? { render } : undefined);
+        } else {
+          runtime.runTicks(n, render ? { render } : undefined);
+        }
+        return { ok: true };
+      } catch (err) {
+        return structuredErrorResult(err);
+      }
+    },
+  },
+};

package/contributions/generation.service.ts

@@ -0,0 +1,96 @@
+/**
+ * THE GENERATION ESTATE (`@volter/editor-sdk/services`, a `workspace.service`
+ * contribution): the paid-provider lane's editor surface — the Generations
+ * drawer gallery over the durable job ledger, the Create-generation document
+ * and the per-job result document.
+ *
+ * They were host modules (`generation-jobs.ts`, `components/GenerationActivity
+ * .tsx`, `components/generation-documents.tsx`, `components/generation-
+ * presentation.ts`), which put a metered service's ledger, its provider
+ * vocabulary and its billing strings inside a base library for making IDEs
+ * (WORK.md §The open-source launch, phase 1 unit 6). Nothing here is generic
+ * over document kinds or surfaces; every line is about one lane.
+ *
+ * TWO DOORS, both already the host's:
+ *  - the drawer TAB is `registerWorkspaceUtility` — a `.utility` contribution
+ *    would be the shorter spelling, but that point carries no attention BADGE
+ *    and the tab's whole job is to say how many results are unseen, so the
+ *    registry call is made here directly (the story documents' service does
+ *    the same, for the same reason);
+ *  - the two DOCUMENTS open through `document-open-registry.ts` under the
+ *    `generation` VIEW ADDRESS — the kind `@volter/editor-sdk`'s `EditorView`
+ *    already names — so `editor-view-presentation.ts` addresses a generation
+ *    without importing one, and a build without this package answers `null`
+ *    to the address instead of pretending.
+ *
+ * The SERVER half (`packages/editor/server/generation-jobs.ts`, the
+ * reconciler, `routes/generations.ts`) is still the editor's: there is no
+ * server-side service point yet (WORKBENCH.md §Contribution points, `service`
+ * — "the SERVER side … is still the editor's"). This module talks to those
+ * routes over HTTP exactly as it did when it lived in the host.
+ */
+
+import { registerDocumentOpener } from '@volter/editor-core/document-open-registry';
+import { CONTRIBUTED_WORKSPACE_UTILITIES } from '@volter/editor-core/workspace-core-utilities';
+import { registerWorkspaceUtility } from '@volter/editor-core/workspace-utility-registry';
+import { GenerationActivity } from '../src/generation/GenerationActivity';
+import {
+  openGenerationCreateDocument,
+  openGenerationDocument,
+} from '../src/generation/generation-documents';
+import {
+  generationJobsSnapshot,
+  generationJobsVersion,
+  generationUnreadCount,
+  refreshGenerationJobs,
+  startGenerationJobActivity,
+  subscribeGenerationJobs,
+} from '../src/generation/generation-jobs';
+
+export const point = 'workspace.service';
+
+/** The `generation` view address (`EditorView['document']`, `@volter/editor-sdk`).
+ *  `id` is a job id, or `create` for the submit document. */
+const GENERATION_VIEW_ADDRESS = 'generation';
+
+function generationsBadge() {
+  const count = generationUnreadCount(generationJobsSnapshot().jobs);
+  return count > 0 ? ({ count, severity: 'info' } as const) : null;
+}
+
+export function start(): () => void {
+  const stops = [
+    // The ledger POLL, and its cadence, are this lane's own: it was
+    // `EditorContext.tsx`'s `useEffect`, so the host held a 2-second timer for
+    // a metered service. Deliberately NOT `session.onSample` — that door is the
+    // five-second VITALS tick for derivations of the session, and hanging a
+    // remote-ledger fetch on it would slow a visible result by 3s for no
+    // measured reason. The service owns the interval and ends it on stop.
+    startGenerationJobActivity(),
+    registerWorkspaceUtility({
+      ...CONTRIBUTED_WORKSPACE_UTILITIES.generations,
+      order: 15,
+      Content: GenerationActivity,
+      badge: generationsBadge,
+      subscribeBadge: subscribeGenerationJobs,
+      badgeSnapshot: generationJobsVersion,
+      visibleByDefault: false,
+      closeable: true,
+    }),
+    registerDocumentOpener<{ readonly id: string }>({
+      id: GENERATION_VIEW_ADDRESS,
+      owner: '@volter/editor-game/generation',
+      open: (_store, request) => {
+        if (request.id === 'create') return openGenerationCreateDocument();
+        const job = generationJobsSnapshot().jobs.find((entry) => entry.id === request.id);
+        return job ? openGenerationDocument(job) : null;
+      },
+      // A job the page has not fetched yet is not a missing job: refresh the
+      // ledger once and the address resolves.
+      settle: refreshGenerationJobs,
+    }),
+  ];
+  return () => {
+    for (const stop of stops) stop();
+  };
+}

package/contributions/generations.status.tsx

@@ -0,0 +1,53 @@
+/**
+ * GENERATIONS in the status bar (`workspace.status`) — permanent access to the
+ * paid-provider lane's results, including when there are none yet.
+ *
+ * It was `status-contributions.tsx`'s `GenerationsStatus`, a host module, so
+ * the base host named the generation ledger to paint a pill. The pill is the
+ * same; what changed is who owns it (WORK.md §The open-source launch, phase 1
+ * unit 6 — the generation estate is a service lane, not a base library's
+ * concern).
+ */
+
+import { CONTRIBUTED_WORKSPACE_UTILITIES } from '@volter/editor-core/workspace-core-utilities';
+import { editorHost } from '@volter/editor-sdk/host';
+import { Button } from '@volter/editor-sdk/widgets';
+import { useSyncExternalStore } from 'react';
+import {
+  generationJobIsActive,
+  generationJobsSnapshot,
+  generationUnreadCount,
+  subscribeGenerationJobs,
+} from '../src/generation/generation-jobs';
+
+export const point = 'workspace.status';
+export const title = 'Generations';
+export const align = 'left';
+export const order = 24;
+
+export default function GenerationsStatus() {
+  const { jobs } = useSyncExternalStore(
+    subscribeGenerationJobs,
+    generationJobsSnapshot,
+    generationJobsSnapshot,
+  );
+  const unseen = generationUnreadCount(jobs);
+  const running = jobs.filter(generationJobIsActive).length;
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      size="compact"
+      className="vgai-status-action"
+      data-testid="status-generations"
+      aria-label={`Generations, ${unseen} unseen, ${running} running`}
+      title={`${unseen} unseen generation results, ${running} running — open Generations`}
+      onClick={() =>
+        editorHost().workspace.showUtility(CONTRIBUTED_WORKSPACE_UTILITIES.generations.id)
+      }
+    >
+      Generations · {unseen}
+      {running > 0 ? ` · ${running} running` : ''}
+    </Button>
+  );
+}

package/contributions/ingest.service.ts

@@ -0,0 +1,80 @@
+/**
+ * THE INGEST LANE, started (`@volter/editor-sdk/services`, a
+ * `workspace.service` contribution).
+ *
+ * Three jobs, and the order matters:
+ *
+ * 1. IMPORTING the lane's modules is what runs their registrations. A package
+ *    module runs only when something imports it, and the lane's live-session
+ *    registration, its `ingest`/`ingestCaptureWait` state facets and its
+ *    `onShellStore` binding are module-load side effects of
+ *    `mount-ingest-root.ts`. The static import below is therefore load-bearing
+ *    — `vgai status` carries `ingest: null` / `ingestCaptureWait: null` before
+ *    contribution pass. A product that composes no `@volter/editor-game` reports
+ *    neither key, which is the honest state: no lane claims to mount
+ *    unmodified games.
+ *
+ * 2. AUTO-LAUNCH on `project.onReady`. The two boot chains (`the world root's stage`,
+ *    `NonThreeAuthoringBootstrap`) used to call `autoLaunchIngest(store)` by
+ *    name; they now only run the project-ready hook, and this is its first
+ *    registrant (WORK.md §P4). That hook is LATCHED per project, because a
+ *    contribution pass can finish on either side of the boot chain;
+ *    `autoLaunchIngest`'s own dedupe makes the second arrival a no-op. And
+ *    `hosted-example.ts`'s auto-play decision still runs AFTER the hook, so
+ *    `isIngestActive()` is answered by a mount this hook already made.
+ *
+ * 3. REGISTERING THIS LANE'S ADAPTER DECLARATIONS. A repo-vendored game does
+ *    not ship its own `vgai.adapter.ts` — by the REALM rule its host-realm
+ *    declaration lives in the in-tree registry (`@editor/ingest/registry`),
+ *    which the host used to import directly and therefore carried in every
+ *    editor boot, a `models` build that mounts no unmodified game included.
+ *    The host now owns only the PRECEDENCE and asks a registered source
+ *    (`@editor/project-adapter`'s `registerAdapterDefinitionSource`); this lane owns the table,
+ *    because these are ITS declarations for content IT mounts. The host WAITS
+ *    for this registration when a project's manifest declares an ingest root
+ *    — a contract fact it reads before any contribution loads — so the
+ *    registration arriving on the contribution pass is on time by
+ *    construction, never a re-mount after a wrong one.
+ *
+ * The store comes from `@editor/shell-store-door`, the same arrival
+ * `mount-ingest-root.ts` binds itself on — read at launch time rather than
+ * captured, so neither ordering can leave the launch holding `null`.
+ */
+import { editorConsole } from '@volter/editor-core/editor-console';
+import { importIngestAdapterModule, ingestAdapterModulePath } from '../src/host/ingest/registry';
+import { registerAdapterDefinitionSource } from '@volter/editor-core/project-adapter';
+import { shellStoreForHost } from '@volter/editor-core/shell-store-door';
+import { editorHost } from '@volter/editor-sdk/host';
+import { autoLaunchIngest } from '../src/ingest/mount-ingest-root';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  const stopSource = registerAdapterDefinitionSource({
+    id: 'in-tree-ingest-registry',
+    owner: '@volter/editor-game/contributions/ingest.service.ts',
+    modulePathFor: (rootId) => ingestAdapterModulePath(rootId),
+    // A module that exists and throws is left to throw: `defineAdapter`
+    // validates at evaluation time, and the host names that failure by path
+    // rather than swallowing it into the native default.
+    importModule: async (rootId) => await importIngestAdapterModule(rootId),
+  });
+  const stopReady = editorHost().project.onReady(async () => {
+    const store = shellStoreForHost();
+    if (!store) {
+      // The store arrives with `AppRoot`, long before any boot chain reaches
+      // ready, so this cannot happen quietly — say so rather than skipping an
+      // auto-launch the manifest asked for.
+      editorConsole.error(
+        'Ingest auto-launch skipped: the editor shell store had not arrived at project ready.',
+        'ingest',
+      );
+      return;
+    }
+    await autoLaunchIngest(store);
+  });
+  return () => {
+    stopReady();
+    stopSource();
+  };
+}

package/contributions/instances.command.ts

@@ -0,0 +1,75 @@
+/**
+ * The INSTANCE verbs of the session wire (`@volter/editor-sdk/commands`, a
+ * `workspace.command` contribution): how many instances of the game play
+ * split-screen, and which exist.
+ *
+ * Play mode and the live instance registry are the game skew's own modules,
+ * still housed in the editor until Play leaves the host (WORK.md §The
+ * workbench, G); they are reached through the `@editor/*` alias the editor's
+ * Vite serves to every contribution, and become this package's own imports
+ * when they move. Nothing here is host API.
+ */
+
+import { liveInstanceIds } from '@volter/editor-core/authoring/active-systems';
+import type { CommandContribution } from '@volter/editor-sdk/commands';
+import {
+  instanceEntries,
+  isPlayModeActive,
+  setDesiredExtraInstances,
+  setDesiredInstanceNames,
+} from '../src/play/play-mode';
+
+export const point = 'workspace.command';
+
+const notPlaying = () => ({
+  ok: false,
+  error: 'not in play mode — start play before using the debug seam',
+});
+
+export const commands: CommandContribution['commands'] = {
+  // Multiplayer authoring: how many instances of this game to show
+  // split-screen (total, including the primary). The GamePanel reconciles by
+  // mounting/unmounting extra instances to match. Requires a live play
+  // session — there is no primary to sit beside otherwise — and reads as a
+  // no-op-that-lies if silently ignored, so it fails loudly when stopped.
+  'set-instance-count': {
+    derivedRefresh: 'always',
+    handle: (cmd) => {
+      if (!isPlayModeActive()) return notPlaying();
+      // `names` (optional) labels the instances (index 0 = primary); its length
+      // is then the total count. Otherwise `count` is the total, with default
+      // "Player N" labels.
+      const names = cmd['names'];
+      if (Array.isArray(names) && names.every((n) => typeof n === 'string')) {
+        if (names.length < 1) {
+          return { ok: false, error: 'set-instance-count "names" must have at least one entry.' };
+        }
+        setDesiredInstanceNames(names as string[]);
+        return { ok: true };
+      }
+      const count = cmd['count'];
+      if (typeof count !== 'number' || !Number.isFinite(count) || count < 1) {
+        return {
+          ok: false,
+          error: `set-instance-count requires a whole "count" >= 1 (or a "names" array), got ${String(count)}.`,
+        };
+      }
+      setDesiredExtraInstances(Math.floor(count) - 1);
+      return { ok: true };
+    },
+  },
+  // The instance-enumeration op — the ONE session-wire question that must
+  // NOT route through the bridge: it answers "which instances exist", and the
+  // bridge RESOLVES an instance (and refuses when several are live), so
+  // asking it "which exist" is the exact ambiguity it throws on. Returns the
+  // live mount ids so `@volter/editor-live`'s `game.instances()` can hand back one
+  // addressed `GameClient` per id. No play gate: `liveInstanceIds()` is `[]`
+  // when nothing is mounted, which is the honest answer, not a precondition
+  // failure. `named` adds the friendly labels a HUD/driver shows ("Player
+  // 2"), from the play-mode instances (ids without a play-mode name — e.g. an
+  // ingest mount — simply do not appear in `named`).
+  'list-instances': {
+    derivedRefresh: 'if-content-changed',
+    handle: () => ({ ok: true, data: { instances: liveInstanceIds(), named: instanceEntries() } }),
+  },
+};

package/contributions/navmesh.menu.ts

@@ -0,0 +1,39 @@
+/**
+ * Debug ▸ Bake/Clear NavMesh — the navmesh session verbs as menu items.
+ *
+ * Both dispatch the window events `../src/navmesh/navmesh-handler.ts` listens
+ * on (started by `navmesh.service.ts`), through `../src/navmesh/navmesh-actions.ts`:
+ * the handler and the trigger import the SAME names, so a rename cannot
+ * silently unwire the control. The whole cluster — handler, event names,
+ * workflow store — is this package's now (P6b); no host module reads it.
+ *
+ * `disabled` and the Bake label are asked at render, and the host samples them
+ * on its availability tick while a menu is open, so they follow the mounted
+ * game's `NavigationAdapter` and a bake in flight.
+ */
+import { getActiveSystems } from '@volter/editor-core/authoring/active-systems';
+import type { MenuContribution } from '@volter/editor-sdk/chrome';
+import { dispatchNavMeshBake, dispatchNavMeshClear } from '../src/navmesh/navmesh-actions';
+import { navBakeBusy, navMeshBaked } from '../src/navmesh/navmesh-workflow-store';
+
+export const point = 'workspace.menu';
+
+export const menu: MenuContribution = {
+  menu: 'debug',
+  items: [
+    {
+      id: 'navmesh-bake',
+      label: () => (navMeshBaked() ? 'Rebake NavMesh' : 'Bake NavMesh'),
+      testId: 'navmesh-bake',
+      disabled: () => navBakeBusy() || !getActiveSystems().navigation?.bake,
+      execute: dispatchNavMeshBake,
+    },
+    {
+      id: 'navmesh-clear',
+      label: 'Clear NavMesh',
+      testId: 'navmesh-clear',
+      disabled: () => navBakeBusy() || !navMeshBaked() || !getActiveSystems().navigation?.clear,
+      execute: dispatchNavMeshClear,
+    },
+  ],
+};

package/contributions/navmesh.service.ts

@@ -0,0 +1,19 @@
+/**
+ * THE NAVMESH SESSION HANDLER (`@volter/editor-sdk/services`, a
+ * `workspace.service` contribution): the listener behind Debug ▸ Bake /
+ * Clear NavMesh (`navmesh.menu.ts`), which bakes the authoring scene's
+ * walkable-tagged meshes through the mounted game's `NavigationAdapter` and
+ * shows the result as the viewport's `navmesh` helper.
+ *
+ * It was a mount effect in the host's one-and-only scene panel, so a
+ * build with no `@volter/editor-game` still carried it and that panel owned its
+ * lifetime. A service instead: the contribution pass starts it and stops it
+ * before the next one, and no stage names a lane.
+ */
+import { setupNavMeshHandlers } from '../src/navmesh/navmesh-handler';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  return setupNavMeshHandlers();
+}

package/contributions/network.utility.tsx

@@ -0,0 +1,17 @@
+/**
+ * The Network inspector as a drawer tab (W3b): replicated-state tree,
+ * message log, rate sparklines and the conditioner over the inspected
+ * session's `NetworkingAdapter`. On offer only while such an adapter is
+ * registered — a tab over nothing would be a measurement nobody made.
+ */
+import { editorHost } from '@volter/editor-sdk/host';
+import { NetworkInspectorPanel } from '../src/network/NetworkInspectorPanel';
+
+export const point = 'workspace.utility';
+export const title = 'Network';
+export const order = 25;
+export const available = (): boolean => editorHost().systems.inspectedNetworking() !== null;
+
+export default function NetworkUtility() {
+  return <NetworkInspectorPanel />;
+}