@volter/editor-game 0.5.65

package/contributions/coverage.service.ts

@@ -0,0 +1,118 @@
+/**
+ * CAPABILITY COVERAGE (`@volter/editor-sdk/services`, a `workspace.service`
+ * contribution): the four derived families that GRADE a mounted game's
+ * adapters, and the union headline the editor console says out loud.
+ *
+ * ## Why this is the game skew's and not the host's
+ *
+ * Every row here is a question about a GAME — which providers this root's
+ * `AuthoringAdapter` exposes, which `SystemAdapters` slots the running game
+ * bound, whether the open project can build and prove itself, whether its
+ * adapter table became real Edit documents. A host with no game skew loaded
+ * (the models build) has no adapters to grade and asked none of it; it kept
+ * paying for the derivation anyway, because the families were host fields on
+ * `collectState` and a direct call in the host's vitals tick.
+ *
+ * ## The two doors, both the host's own, neither of them new vocabulary
+ *
+ *  - `session.reportFacet(collect, { reusableKeys })` — the four `vgai status`
+ *    facets. The keys are declared REUSABLE because grading a root re-walks
+ *    its tree (76ms–1.3s, measured), which is exactly the cost
+ *    `command-listener.ts`'s `REUSABLE_DERIVED_FACETS` exists to keep off the
+ *    interaction path: a collect handed a `reuse` snapshot copies them, and
+ *    the host strips them from an interaction PATCH by name.
+ *  - `session.onSample(fn)` — the host's own five-second vitals sample
+ *    (`coverage/session-vitals.ts`), which `reportSessionCoverage` used to be
+ *    a direct call inside. Subscribing keeps the promise that module's header
+ *    makes: ONE watcher, one instant, one answer per cadence. A second
+ *    interval here would sample the same session a fraction of a second later
+ *    and publish a second story about one moment.
+ *
+ * A `restart` says "my project's files changed", so the project family's file
+ * cache is dropped on it — through `session.onCommandDispatched`, the door
+ * that already reports every relayed command, rather than a line in the
+ * host's dispatch naming this package.
+ */
+import { editorHost } from '@volter/editor-sdk/host';
+import { authoringSurfaceCoverage } from '../src/coverage/live-authoring-surface';
+import {
+  invalidateProjectFileFacts,
+  projectVerbCoverage,
+} from '../src/coverage/live-project-verbs';
+import { nativeSystemCoverage } from '../src/coverage/native-system-coverage';
+import { rootCoverageFacet } from '../src/coverage/root-coverage';
+import { reportSessionCoverage } from '../src/coverage/session-coverage';
+
+export const point = 'workspace.service';
+
+/** The four keys this facet serves, and the ones the host strips from an
+ *  interaction patch. Named once. */
+const REUSABLE_KEYS = [
+  'rootCoverage',
+  'systemCoverage',
+  'projectCoverage',
+  'authoringCoverage',
+] as const;
+
+function coverageFacets(reuse: Record<string, unknown> | null): Record<string, unknown> {
+  if (reuse)
+    return {
+      rootCoverage: reuse['rootCoverage'] ?? [],
+      systemCoverage: reuse['systemCoverage'] ?? null,
+      projectCoverage: reuse['projectCoverage'] ?? null,
+      authoringCoverage: reuse['authoringCoverage'] ?? null,
+    };
+  const systems = nativeSystemCoverage();
+  const project = projectVerbCoverage();
+  const authoring = authoringSurfaceCoverage();
+  return {
+    // THE DERIVED COVERAGE, per mounted root — native and ingested alike. The
+    // row vocabulary is generated from the `AuthoringAdapter` contract itself
+    // (`src/coverage/root-coverage.ts`), so a capability nobody remembered to
+    // enumerate still appears here as a standing row. `[]` when nothing is
+    // mounted, which is not the same as "no gaps".
+    rootCoverage: rootCoverageFacet().map((entry) => ({
+      worldId: entry.worldId,
+      surface: entry.surface,
+      summary: entry.report.summary,
+      rows: entry.report.rows.map((row) => ({ ...row })),
+    })),
+    // The GAME-scoped companion to `rootCoverage`: one row per
+    // `SystemAdapters` slot, read off the editor's own live registry. `null`
+    // for an ingested mount, whose declared-carrier measurement in
+    // `ingest.coverage` is stronger, and for a session with no open project.
+    systemCoverage: systems
+      ? { summary: systems.summary, rows: systems.rows.map((row) => ({ ...row })) }
+      : null,
+    // The THIRD derived family, and the one that lives outside both adapter
+    // contracts: the native verbs whose subject is the PROJECT rather than a
+    // mounted root — its committed proof route, whether `vgai add` can land a
+    // capability here, and whether it can produce a standalone build at all
+    // (`@editor/coverage/project-verb-coverage`). Without it a project could
+    // be green in the other two families and silently have none of the three.
+    // `null` only when no project is open.
+    projectCoverage: project
+      ? { summary: project.summary, rows: project.rows.map((row) => ({ ...row })) }
+      : null,
+    // The PROJECT-level authoring surface: whether the resolved adapter table
+    // became real Edit documents and Content pieces. Runtime/root coverage can
+    // be green while both are absent, so this family has its own status facet.
+    authoringCoverage: authoring
+      ? { summary: authoring.summary, rows: authoring.rows.map((row) => ({ ...row })) }
+      : null,
+  };
+}
+
+export function start(): () => void {
+  const session = editorHost().session;
+  const stopFacet = session.reportFacet(coverageFacets, { reusableKeys: REUSABLE_KEYS });
+  const stopSample = session.onSample(reportSessionCoverage);
+  const stopCommands = session.onCommandDispatched((type) => {
+    if (type === 'restart') invalidateProjectFileFacts();
+  });
+  return () => {
+    stopFacet();
+    stopSample();
+    stopCommands();
+  };
+}

package/contributions/edit-mode-audio.service.ts

@@ -0,0 +1,23 @@
+/**
+ * EDIT-TIME AUDIO (`@volter/editor-sdk/services`, a `workspace.service`
+ * contribution): the first-party Three/Web Audio graph the editor inspects
+ * while nothing is playing, so Stop falls back to a real adapter instead of
+ * making audio disappear.
+ *
+ * Install-once and project-independent, like `audio-unlock.service.ts` beside
+ * it — the graph is the page's, not the open project's — so this has no
+ * `onProjectChange` re-install, unlike edit-time networking.
+ *
+ * It was `components/EditModeAudioBootstrap.tsx`, a component that rendered
+ * `null` so the shell's layout could run an effect, and through it the host
+ * imported `@volter/game-runtime/setup/setup-audio`, `@volter/game-runtime/audio/bus-mixer` and
+ * `@volter/game-runtime/audio/pose-guard` — the engine's audio RUNTIME — into every editor
+ * boot (WORK.md §The open-source launch, phase 1 unit 7).
+ */
+import { installEditModeAudio } from '../src/edit-mode/edit-mode-audio';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  return installEditModeAudio();
+}

package/contributions/edit-mode-networking.service.ts

@@ -0,0 +1,30 @@
+/**
+ * EDIT-TIME NETWORKING (`@volter/editor-sdk/services`, a `workspace.service`
+ * contribution): the networking adapter the editor inspects while nothing is
+ * playing, bound to the open project's own Colyseus client/room exports.
+ *
+ * Unlike audio (universal, install-once), it is project-dependent — it
+ * installs only when the open project declares a server — so it re-installs
+ * on every project change.
+ *
+ * It was `components/EditModeNetworkingBootstrap.tsx`, a component that
+ * rendered `null` so the shell's layout could run an effect. A service is what
+ * that always was, and the shell no longer names it (WORK.md §The workbench,
+ * P3b).
+ */
+import { onProjectChange } from '@volter/editor-core/project-manager';
+import { installEditModeNetworking } from '../src/edit-mode/edit-mode-networking';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  let dispose = installEditModeNetworking();
+  const stop = onProjectChange(() => {
+    dispose();
+    dispose = installEditModeNetworking();
+  });
+  return () => {
+    stop();
+    dispose();
+  };
+}

package/contributions/game-document.service.ts

@@ -0,0 +1,25 @@
+/**
+ * THE GAME DOCUMENT's content, registered (`@volter/editor-sdk/services`, a
+ * `workspace.service` contribution). The host owns the live document's
+ * LIFETIME — `workspace:game` opens when a lane acquires it and closes on the
+ * playing → stopped edge (`live-document.ts`) — and this package owns what it
+ * DRAWS: the panel a runtime mounts into and the document-local toolbar
+ * (resolution, device emulation, instance inspection, debug draw, frame
+ * capture).
+ *
+ * A service rather than a module-load side effect, so the registration is
+ * paired with an unregistration the host runs before the next contribution
+ * pass — a build that drops `@volter/editor-game` leaves the host with no live content
+ * and the door's own `NoLiveContent` placeholder, which is the honest state.
+ */
+import { editorHost } from '@volter/editor-sdk/host';
+import { GameDocumentContent, GameDocumentToolbar } from '../src/game-document/GameDocument';
+
+export const point = 'workspace.service';
+
+export function start(): () => void {
+  return editorHost().workspace.liveDocument.register({
+    Content: GameDocumentContent,
+    Toolbar: GameDocumentToolbar,
+  });
+}

package/contributions/game-eval.command.ts

@@ -0,0 +1,210 @@
+/**
+ * The STEP verbs of the session wire (`@volter/editor-sdk/commands`, a
+ * `workspace.command` contribution): `game-eval`, the module lane behind
+ * `vgai eval`'s `game.run(...)`, and `page-script`, the in-page Playwright
+ * shim behind `page(...)`. Both carry a step function's own SOURCE over the
+ * wire and reconstruct it here — closures do not survive the trip — so both
+ * are gated on a live game surface (a play session or an ingest mount) and
+ * rooted at the game container, never editor chrome.
+ *
+ * The module lane's page-side door (`window.__vgaiGameEval`) and the two
+ * providers it needs are installed when this module loads, which is when the
+ * verbs themselves become available: one handler, two doors, registered
+ * together.
+ *
+ * Play mode, the module resolver and the shim 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 { createGameModuleResolver, setFocusedInstanceProvider } from '../src/host/game-module-access';
+import { createPageShim, PageShimUnsupportedError } from '../src/host/playwright-shim';
+import type {
+  CommandContribution,
+  EditorCommandMessage,
+  EditorCommandResult,
+} from '@volter/editor-sdk/commands';
+import { notPlayingResult } from '../src/command-results';
+import { isIngestActive } from '../src/ingest/active-ingest';
+import { focusedInstanceId, getGameContainer, isPlayModeActive } from '../src/play/play-mode';
+
+export const point = 'workspace.command';
+
+/**
+ * `game-eval` relay op — THE MODULE LANE. Reconstructs a step function's
+ * source in the editor page (same wire contract as `page-script`: closures do
+ * not survive) and runs it against a scope of { page, modules, instanceId } —
+ * `modules(path)` importing the RUNNING mount's own module instances
+ * (`game-module-access.ts`). This is what makes `vgai eval` able to touch the
+ * game's exported modules directly, in the browser, with no registry: the
+ * step is literal JS against the game's real functions.
+ *
+ * The result must survive the wire: anything unserializable is refused BY
+ * NAME rather than mangled — return plain data, not live objects.
+ */
+/**
+ * The Playwright-host door to the SAME handler: a real `page.evaluate` cannot
+ * reach relay ops, so the hook exposes `game-eval` inside the page itself.
+ * One handler, two doors — the lanes cannot drift.
+ */
+declare global {
+  interface Window {
+    __vgaiGameEval?: (src: string, instance?: string) => Promise<unknown>;
+  }
+}
+if (typeof window !== 'undefined') {
+  setFocusedInstanceProvider(focusedInstanceId);
+  window.__vgaiGameEval = async (src: string, instance?: string) => {
+    const result = await handleGameEval({
+      type: 'game-eval',
+      src,
+      ...(instance === undefined ? {} : { instance }),
+    } as unknown as EditorCommandMessage);
+    if (!result.ok) throw new Error(result.error ?? 'game-eval failed');
+    return (result.data as { result?: unknown } | undefined)?.result ?? null;
+  };
+}
+
+async function handleGameEval(cmd: EditorCommandMessage): Promise<EditorCommandResult> {
+  if (!isPlayModeActive() && !isIngestActive()) return notPlayingResult();
+  const src = cmd['src'];
+  if (typeof src !== 'string') {
+    return { ok: false, error: 'game-eval requires a string "src" (the step\'s toString())' };
+  }
+  const container = getGameContainer();
+  if (!container) {
+    return {
+      ok: false,
+      error: 'game-eval: no play-mode game container is mounted yet',
+      data: { code: 'GAME_EVAL_ERROR' },
+    };
+  }
+  const instanceRaw = cmd['instance'];
+  const instanceId = typeof instanceRaw === 'string' ? instanceRaw : undefined;
+  let step: (scope: unknown) => unknown;
+  try {
+    step = new Function('scope', `return (${src})(scope)`) as (scope: unknown) => unknown;
+  } catch (err) {
+    return {
+      ok: false,
+      error: `game-eval: failed to reconstruct the step function from source — ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      data: { code: 'GAME_EVAL_ERROR' },
+    };
+  }
+  const scope = {
+    page: createPageShim(container),
+    modules: createGameModuleResolver(instanceId),
+    instanceId: instanceId ?? focusedInstanceId(),
+  };
+  try {
+    const result = await step(scope);
+    const value = result === undefined ? null : result;
+    try {
+      JSON.stringify(value);
+    } catch {
+      return {
+        ok: false,
+        error:
+          'game-eval: the step returned an unserializable value ' +
+          `(${Object.prototype.toString.call(value)}) — return plain data (numbers, strings, ` +
+          'arrays, plain objects), not live module objects.',
+        data: { code: 'GAME_EVAL_UNSERIALIZABLE' },
+      };
+    }
+    return { ok: true, data: { result: value } };
+  } catch (err) {
+    return {
+      ok: false,
+      error: `game-eval step failed: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`,
+      data: { code: 'GAME_EVAL_ERROR' },
+    };
+  }
+}
+
+/**
+ * `page-script` relay op handler — "the playwright shim in the editor
+ * page + script-mode wire op". Standalone command (like `bridge-screenshot`,
+ * its sibling in `bridge.command.ts`),
+ * NOT a `bridge-call` method: this is editor-page UI automation, not the
+ * game-debug seam, so it deliberately stays outside `dispatchBridgeMethod`'s
+ * switch — the bridge↔wire parity gate (`bridge-wire-parity.test.ts`) only
+ * walks THAT switch, and must never need to know about this op.
+ *
+ * `cmd['src']` is a UI-automation step's `Function.prototype.toString()`
+ * source (`@volter/editor-live`'s `RelayTransport.runPageScript` — see that file's
+ * doc comment for the client-facing half of the wire contract). Reconstructed
+ * here with `new Function` and run against a fresh `createPageShim` rooted at
+ * the SAME game container `bridge-screenshot`'s composite capture uses
+ * (`getGameContainer` — never editor chrome). `PageShimUnsupportedError`
+ * (thrown the instant the step touches an unimplemented `Page`/`Locator`
+ * member) is distinguished from any other step failure so a caller can tell
+ * "this shim doesn't support that yet" apart from "the step's own assertion
+ * failed" — both are structured failures, never a hang or a silent
+ * mis-report.
+ */
+async function handlePageScript(cmd: EditorCommandMessage): Promise<EditorCommandResult> {
+  // An ingest mount IS the live game surface even though it never creates a
+  // first-party `play-mode.ts` session. Keep the Playwright-style page door on
+  // the same reachability rule as bridge calls/screenshots: a real ingest
+  // container is sufficient, while the genuinely-unmounted case still
+  // refuses below. Without this, `vgai play` could start an ingested game and
+  // `game.commands()` would work, yet `page(...)` answered "not in play mode"
+  // against that very same visible game.
+  if (!isPlayModeActive() && !isIngestActive()) return notPlayingResult();
+  const src = cmd['src'];
+  if (typeof src !== 'string') {
+    return { ok: false, error: 'page-script requires a string "src" (the step\'s toString())' };
+  }
+  const container = getGameContainer();
+  if (!container) {
+    return {
+      ok: false,
+      error: 'page-script: no play-mode game container is mounted yet',
+      data: { code: 'PAGE_SCRIPT_ERROR' },
+    };
+  }
+  let step: (page: unknown) => unknown;
+  try {
+    // Reconstructing a wire-carried step's source is the documented wire
+    // contract (decision 2) — the same limitation class as
+    // Playwright's own evaluate serialization: closures over anything
+    // outside the step's own body do NOT survive the trip.
+    step = new Function('page', `return (${src})(page)`) as (page: unknown) => unknown;
+  } catch (err) {
+    return {
+      ok: false,
+      error: `page-script: failed to reconstruct the step function from source — ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      data: { code: 'PAGE_SCRIPT_ERROR' },
+    };
+  }
+  const page = createPageShim(container);
+  try {
+    const result = await step(page);
+    return { ok: true, data: { result: result === undefined ? null : result } };
+  } catch (err) {
+    if (err instanceof PageShimUnsupportedError) {
+      return {
+        ok: false,
+        error: err.message,
+        data: { code: 'PAGE_SHIM_UNSUPPORTED', member: err.member, supported: [...err.supported] },
+      };
+    }
+    return {
+      ok: false,
+      error: `page-script: step threw — ${err instanceof Error ? err.message : String(err)}`,
+      data: { code: 'PAGE_SCRIPT_ERROR' },
+    };
+  }
+}
+
+export const commands: CommandContribution['commands'] = {
+  // THE MODULE LANE: an in-page step over { page, modules, instanceId }.
+  'game-eval': { timeoutMs: 60_000, derivedRefresh: 'always', handle: handleGameEval },
+  'page-script': { timeoutMs: 60_000, derivedRefresh: 'always', handle: handlePageScript },
+};

package/contributions/game.layout.ts

@@ -0,0 +1,19 @@
+/**
+ * The GAME workspace — building and playing the game: the editor's standing
+ * arrangement, unchanged (`@volter/editor-sdk/looks`, a `workspace.layout`
+ * contribution). It applies to every project the game editor opens: a
+ * project with no root yet is a game not yet begun, and the Game workspace is
+ * where its first root is added. No captured state: the dock's own reconcile
+ * builds the standing arrangement from nothing.
+ */
+import type { WorkspaceLayoutContribution } from '@volter/editor-sdk/looks';
+
+export const point = 'workspace.layout';
+export const layout: WorkspaceLayoutContribution = {
+  id: 'game',
+  title: 'Game',
+  description:
+    "Building and playing the game: the editor's standing arrangement, unchanged. The default.",
+  // Game authoring uses the viewport's floating controls; Blender owns its header row.
+  regions: { header: 'hidden' },
+};