@volter/play 0.5.212 → 0.5.214

package/src/editor-blender.ts

@@ -1,19 +1,14 @@
 /**
- * EDITOR-BLENDER'S API, AS PLAY'S PAGE HALF KEPT IT (`../contributions/play.page.tsx`), and the model
- * Play that page half registered through it. play's modules read them here rather than importing
- * editor-blender's modules: its API is the one instance editor-blender's own `activate` returned.
+ * EDITOR-BLENDER'S API, AS PLAY'S PAGE HALF KEPT IT (`../contributions/play.page.tsx`). play's modules read it here
+ * rather than importing editor-blender's modules: its API is the one instance editor-blender's own `activate` returned.
  */
-import type { BlenderPageApi, DocumentPlayExtension } from '@volter/editor-blender/api';
+import type { BlenderPageApi } from '@volter/editor-blender/api';
 
 let api: BlenderPageApi | null = null;
-let modelPlay: DocumentPlayExtension | null = null;
-const listeners = new Set<() => void>();
 
 /** Kept by play's `activate`, and released (`null`) when it deactivates. */
-export function keepEditorBlender(next: BlenderPageApi | null, registered: DocumentPlayExtension | null): void {
+export function keepEditorBlender(next: BlenderPageApi | null): void {
   api = next;
-  modelPlay = registered;
-  for (const listener of listeners) listener();
 }
 
 /** editor-blender's API. play's modules run once its page half has activated, which is after editor-blender's. */
@@ -21,13 +16,3 @@ export function editorBlender(): BlenderPageApi {
   if (!api) throw new Error("@volter/play is not active, so editor-blender's API is not at hand.");
   return api;
 }
-
-/** The model Play play registered, or `null` while it is not. */
-export function registeredModelPlay(): DocumentPlayExtension | null {
-  return modelPlay;
-}
-
-export function subscribeRegisteredModelPlay(listener: () => void): () => void {
-  listeners.add(listener);
-  return () => { listeners.delete(listener); };
-}

package/src/editor-threejs.ts

@@ -1,6 +1,6 @@
 /**
  * EDITOR-THREEJS'S API, AS PLAY'S PAGE HALF KEPT IT (`../contributions/play.page.tsx`): the shared viewport and its
- * stages, which a std level's Scene view draws in (`../contributions/std-scene.document.tsx`). play reads it here rather than importing
+ * stages, which a std level in code is drawn in (`../contributions/std-level.document.tsx`). play reads it here rather than importing
  * editor-threejs's modules: its API is the one instance editor-threejs's own `activate` returned.
  */
 import type { ThreePageApi } from '@volter/editor-threejs/api';

package/src/game-controls.ts

@@ -0,0 +1,111 @@
+/**
+ * THE GAME'S CONTROLS, which the Game panel draws (`../contributions/game-panel.tsx`) and its verbs run behind command
+ * ids (`volter.play.<verb>`): Play and Stop, pause, step, speed, Restart and Autoplay, each a call on the run
+ * (`game-run.ts`) or std's own control said to the game's pages (`std-game.ts`, `std-controls.ts`).
+ *
+ * PLAY SAVES THE EDIT FIRST: Play (and Restart) save the `.blend` Blender holds where it changed (a level's or a
+ * prefab's, whichever was edited last), which runs std's level export (`std-level.ts`), and the run's pages load once
+ * that export has run, so the game plays the current edit (`savedEdit`). A save that fails is said in the play log, and
+ * the game plays the level as last exported.
+ *
+ * AUTOPLAY IS THE EDITOR'S SWITCH, and the person always wins: std's own play of one of the game's goals, recorded and
+ * checked, on the player in view while the Game view is on screen and out of view otherwise (`std-game.ts`'s
+ * `setStdAutoplay`); a person's own press in the player's page takes it back, which ends the play. Stopped, it is
+ * armed for the next start.
+ */
+import { armGameAutoplay, gameArm, gamePlaying, restartGame, setGamePlaying, subscribeGameClock } from './game-run';
+import { setStdAutoplay, setStdPaused, setStdSpeed, stdAutoplay, stdRun, stepStd, subscribeStdRun } from './std-game';
+
+/** Autoplay as the panel reads it: on or off, whether it can be switched on and why not, armed
+ *  while stopped, the goals the game's bot offers and the one it plays, and how std's own play of a goal stands
+ *  (`<goal>: playing`, `achieved`, or `failed — why`, `headless ` before it where it plays out of view). */
+export interface GameAutoplay {
+  /** Whether std's play of a goal plays now, wherever it plays (Off ends it). */
+  readonly on: boolean;
+  /** Whether that play drives the player in view, on its page. */
+  readonly driving?: boolean;
+  readonly available: boolean;
+  readonly unavailable?: string | null;
+  readonly armed?: boolean;
+  readonly behaviors?: readonly string[];
+  readonly behavior?: string | null;
+  readonly state?: string | null;
+  /** std's play's report (`build/runs/<run>/report-<n>.json`), once std has written it. */
+  readonly report?: string | null;
+}
+
+/** The save Play runs first (play's page half keeps it, `play.page.tsx`), and the last one Play asked for. */
+let saveEdit: (() => Promise<string | null>) | null = null;
+let saving: Promise<string | null> = Promise.resolve(null);
+
+/** Kept by play's page half while it is active: what saves the edit Blender holds, answering why it failed, if it
+ *  did. */
+export function keepEditSave(save: (() => Promise<string | null>) | null): void {
+  saveEdit = save;
+}
+
+/** The save the run's start waits for, answering why it failed (null: saved, or nothing to save). */
+export const savedEdit = (): Promise<string | null> => saving;
+
+function save(): void {
+  saving = saveEdit?.() ?? Promise.resolve(null);
+}
+
+/** Play (the edit saved first) or Stop. */
+export function playGame(on: boolean): void {
+  if (on && !gamePlaying()) save();
+  setGamePlaying(on);
+}
+
+/** Restart: the edit saved, every player's page loaded afresh; a game not playing simply starts. */
+export function restartPlay(): void {
+  if (!gamePlaying()) { playGame(true); return; }
+  save();
+  restartGame();
+}
+
+export const pauseGame = (paused: boolean): Promise<void> => setStdPaused(paused).then(() => {});
+export const stepGame = (frames = 1): Promise<void> => stepStd(frames).then(() => {});
+export const setGameSpeedOf = (speed: number): Promise<void> => setStdSpeed(speed);
+
+/** Every change of the clock or the run, which Autoplay's state follows. */
+export function subscribeGameControls(listener: () => void): () => void {
+  const stopClock = subscribeGameClock(listener), stopRun = subscribeStdRun(listener);
+  return () => { stopClock(); stopRun(); };
+}
+
+/** The last autoplay state read, and the state it was read over: one snapshot until it changes. */
+let snapshot: { readonly key: string; readonly value: GameAutoplay } | null = null;
+
+export function gameAutoplay(): GameAutoplay {
+  const arm = gameArm();
+  const running = stdRun() !== null;
+  const { on, driving, goal, goals, unavailable, played } = stdAutoplay();
+  const value: GameAutoplay = {
+    on: running && on,
+    driving: running && driving,
+    available: running ? on || unavailable === null : arm === null && goals.length > 0,
+    unavailable: running && !on ? unavailable : null,
+    armed: arm !== null,
+    behaviors: goals,
+    behavior: arm !== null ? arm.goal ?? goal : goal,
+    state: played === null ? null
+      : `${played.device === 'headless' ? 'headless ' : ''}${played.goal}: ${played.state === 'failed' ? `failed — ${played.why ?? 'std did not say why'}` : played.state}`
+        + (played.checks === null ? '' : ` · ${played.checks}`),
+    report: played?.report ?? null,
+  };
+  const key = JSON.stringify(value);
+  if (snapshot?.key !== key) snapshot = { key, value };
+  return snapshot.value;
+}
+
+/** Switch the bot on (the game playing) or off, with `goal` (the game's own when absent). */
+export function setGameAutoplay(on: boolean, by: 'panel' | 'cli', goal?: string): Promise<void> {
+  if (!stdRun()) throw new Error('Nothing is playing; `play` starts it, then `play autoplay on`.');
+  return setStdAutoplay(on, by, goal);
+}
+
+/** Arm (or disarm) Autoplay for the next start, while stopped. */
+export function armAutoplay(armed: boolean, goal?: string): void {
+  armGameAutoplay(armed, goal ?? null);
+}

package/src/game-run.ts

@@ -0,0 +1,165 @@
+/**
+ * THE GAME'S RUN, the project's one (Play in the Game panel, `contributions/game-panel.tsx`; drawn in the Game view,
+ * `game-view.tsx`): whether it plays, its clock as std last answered it, its generation and autoplay armed for its next
+ * start. Kept for the page's life and never stored: a reload opens the editor, not a game.
+ *
+ * THE CLOCK. Pause, step and speed are std's `clock` control on each player's page (`std-controls.ts`); each answer is
+ * the page's clock (`{ paused, speed, time, frame }`), kept here beside whether a game runs and why not, and announced
+ * through the clock's own subscription. The speed is the person's: kept across Plays, and said to each player's page as
+ * it joins. Its time comes from one of two readings, and `from` says which:
+ * - held (paused or stepped): std's answer to the control, exact, as the play log's `pause` and `step` entries record it;
+ * - running: the newest step the viewed player's page traced (std's trace format 3, `s`, sixty a game second from the
+ *   trace's start, since std's live clock is the page's `performance.now`, `adoptLiveClock`). A client page writes a
+ *   trace line only as something happens (an input, a word said, its bot's intent), so this holds while the page is
+ *   idle: it is when the page last traced, not the clock now.
+ *
+ * AUTOPLAY ARMED WHILE STOPPED: the next start drives the viewed player's bot as its page joins, with the goal it was
+ * armed with (`std-game.ts`). Stop drops the arm.
+ */
+const listeners = new Set<() => void>();
+const clockListeners = new Set<() => void>();
+
+/** The speeds the panel offers, slowest first: std's clock takes 0.25 to 4. */
+export const GAME_SPEEDS: readonly number[] = [0.25, 0.5, 1, 2, 4];
+
+export interface GameClock {
+  /** The viewed player's page's game seconds and `tick`, read as `from` says. */
+  readonly time: number;
+  readonly tick: number;
+  /** Where `time` and `tick` were read. `std-answer`: std's answer to the pause or step that held the game (`tick` its
+   *  frame). `newest-traced-step`: the newest step the viewed page traced while the game ran, `time` that step in
+   *  seconds (0 until its trace says a line past its start); it holds while that page traces nothing. After Stop the
+   *  clock keeps the run's last reading and where it was read, with `running` and `paused` false: a reading still in
+   *  flight when its run ended is not written (`std-game.ts`). */
+  readonly from: 'std-answer' | 'newest-traced-step';
+  readonly paused: boolean;
+  /** Simulation seconds per real second; one of `GAME_SPEEDS`. */
+  readonly speed: number;
+  /** The run plays but no game runs: its dev server could not start, or no player's page joined. */
+  readonly failure: string | null;
+  /** A player's page has joined this run. A reader that must know whether Play WORKED (the CLI's `play`) waits for
+   *  this or for `failure`, never for "playing" alone. */
+  readonly running: boolean;
+}
+
+let playing = false;
+/** Replaced, never mutated, so a snapshot read by `useSyncExternalStore` changes identity exactly when it changes
+ *  value. */
+let clock: GameClock = { time: 0, tick: 0, from: 'newest-traced-step', paused: false, speed: 1, failure: null, running: false };
+/** The newest step the viewed page traced, and its seconds: the running clock's reading, kept while the game is held. */
+let traced = { tick: 0, time: 0 };
+/** Bumped by Restart: the Game view runs the game again on it. */
+let generation = 0;
+/** Autoplay armed while stopped, with the goal it drives (null: the game's own). */
+let arm: { readonly goal: string | null } | null = null;
+
+function publish(): void {
+  for (const listener of [...listeners]) listener();
+}
+function publishGameClock(): void {
+  for (const listener of [...clockListeners]) listener();
+}
+function setClock(next: Partial<GameClock>): void {
+  clock = { ...clock, ...next };
+  publishGameClock();
+}
+
+export const gamePlaying = (): boolean => playing;
+
+export function setGamePlaying(value: boolean): void {
+  if (playing === value) {
+    // Stop with nothing playing lets go of an arm made while stopped.
+    if (!value && arm !== null) { arm = null; publishGameClock(); }
+    return;
+  }
+  playing = value;
+  if (value) {
+    // A new run's clock starts at zero and running; the speed is the person's and stays.
+    traced = { tick: 0, time: 0 };
+    setClock({ time: 0, tick: 0, from: 'newest-traced-step', paused: false, failure: null, running: false });
+  } else {
+    arm = null;
+    // The clock keeps the stopped run's time and frames, so `play state` still says how far it got.
+    setClock({ paused: false, failure: null, running: false });
+  }
+  publish();
+}
+
+/** The run's report that no game runs although the run plays (`null` once a player's page joins, which is also the
+ *  moment the run is `running`). */
+export function setGameFailure(failure: string | null): void {
+  const running = failure === null;
+  if (!playing || (clock.failure === failure && clock.running === running)) return;
+  setClock({ failure, running });
+}
+
+/** A page's clock as std answered it (`std-controls.ts`'s `StdClock`), kept as the run's: held, its time and frame
+ *  exactly as answered; running, its speed, the time going back to the newest traced step. */
+export function setGameClock(said: { readonly paused: boolean; readonly speed: number; readonly time: number; readonly frame: number }): void {
+  const next: Pick<GameClock, 'paused' | 'speed' | 'time' | 'tick' | 'from'> = said.paused
+    ? { paused: true, speed: said.speed, time: said.time, tick: said.frame, from: 'std-answer' }
+    : { paused: false, speed: said.speed, ...traced, from: 'newest-traced-step' };
+  if (clock.paused === next.paused && clock.speed === next.speed && clock.time === next.time && clock.tick === next.tick
+    && clock.from === next.from) return;
+  setClock(next);
+}
+
+/** The newest step the viewed player's page traced (std's trace format 3, `s`): the run's clock while it runs. */
+export function setGameTraceStep(step: number, stepsPerSecond: number): void {
+  traced = { tick: step, time: step / stepsPerSecond };
+  if (clock.paused || (clock.tick === step && clock.from === 'newest-traced-step')) return;
+  setClock({ ...traced, from: 'newest-traced-step' });
+}
+
+/** The person's speed, kept for the page's life and said to each player's page as it joins. */
+export function setGameSpeed(speed: number): void {
+  if (!GAME_SPEEDS.includes(speed))
+    throw new Error(`Play speed ${speed} is not one the panel offers: ${GAME_SPEEDS.join(', ')}.`);
+  if (clock.speed !== speed) setClock({ speed });
+}
+
+export function subscribeGame(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+export const gameClock = (): GameClock => clock;
+
+export function subscribeGameClock(listener: () => void): () => void {
+  clockListeners.add(listener);
+  return () => { clockListeners.delete(listener); };
+}
+
+export const gameGeneration = (): number => generation;
+
+/**
+ * BEGIN THE RUN AGAIN. Playing stays true throughout and the generation moves, which is what makes the Game view run
+ * the game again: every player's page loaded afresh. A game that is not playing simply starts.
+ */
+export function restartGame(): void {
+  if (!playing) { setGamePlaying(true); return; }
+  generation += 1;
+  traced = { tick: 0, time: 0 };
+  setClock({ time: 0, tick: 0, from: 'newest-traced-step', paused: false, failure: null, running: false });
+  publish();
+}
+
+/** Autoplay armed for the next start, and the goal it drives; null when it is not armed. */
+export const gameArm = (): { readonly goal: string | null } | null => arm;
+
+/** Arm (or disarm) autoplay for the next start, while stopped: the Game panel's Autoplay button before Play. Disarming
+ *  always succeeds. */
+export function armGameAutoplay(armed: boolean, goal: string | null = null): void {
+  if (armed && playing) throw new Error('The game is already playing; switch autoplay on instead of arming it.');
+  if (armed) arm = { goal };
+  else if (arm === null) return;
+  else arm = null;
+  publishGameClock();
+}
+
+/** The arm taken by the start it was made for. */
+export function takeGameArm(): { readonly goal: string | null } | null {
+  const taken = arm;
+  if (taken !== null) { arm = null; publishGameClock(); }
+  return taken;
+}

package/src/game-view.tsx

@@ -0,0 +1,219 @@
+/**
+ * THE GAME, PLAYED AS THE PROJECT'S (`docs/adr/std-scene-view.md`, decision 8): Play is the project's (`game-run.ts`),
+ * as an engine's Play button is, whatever document is in front, and the game shows in a GAME VIEW of its own, as
+ * Unity's Game view and Godot's Game workspace do. Play opens the Game view as a tab of the editor (`GAME_DOCUMENT`) and
+ * brings it to the front; Stop closes it and brings back the tab that was in front. Another tab in front never stops
+ * the game, and closing the Game view does.
+ *
+ * THE PLAYERS' PAGES OUTLIVE THE TAB'S BOX. The host parks a document's box out of the page while its tab is behind
+ * another, and a frame taken out of the page loads again, so the run draws in the Game view's retained layer
+ * (`@volter/sdk/document-layer`), mounted in the workbench's container, which the Game view's box claims while it is
+ * shown (laid over it, hidden once no view claims it), as Code-OSS keeps a webview that retains its context; the
+ * editor's doors that read the document in front (`editor.document.key`, `query`, `inspect`, `capture`) read the layer as
+ * its content. A hidden layer's pages are throttled, as a hidden retained webview is, and kept.
+ */
+import { type CSSProperties, useLayoutEffect, useRef, useSyncExternalStore } from 'react';
+import { editorHost } from '@volter/sdk/host';
+import { useProgress } from '@volter/sdk/progress';
+import { StateSurface, themeVars } from '@volter/sdk/widgets';
+import { claimDocumentLayer, claimedBox, documentLayer, documentLayerOf, releaseDocumentLayer } from '@volter/sdk/document-layer';
+import {
+  activateWorkspaceDocument,
+  activeWorkspaceDocumentId,
+  closeWorkspaceDocument,
+  openWorkspaceDocument,
+  openWorkspaceDocuments,
+  workspaceDocumentSelection,
+} from '@volter/sdk/workspace-document-registry';
+import { setDocumentPlaySignal } from '@volter/sdk/document-play-extension';
+import { currentStdLevel, StdLevelView, subscribeCurrentStdLevel } from '../contributions/std-level.document';
+import { gameClock, gameGeneration, gamePlaying, setGamePlaying, subscribeGame, subscribeGameClock } from './game-run';
+import { stdRun, stdRunVersion, subscribeStdRun, type GameStage, type StdTileBox } from './std-game';
+
+/** The Game view's id, and the run's: the project's one game. */
+const GAME_DOCUMENT = 'play:game';
+/** The Game view's Scene: the current level's view, live, a view of the Game view's document. */
+const SCENE_VIEW = `${GAME_DOCUMENT}#scene`;
+
+/** The run's stage, made as Play starts and kept across its restarts, in the Game view's retained layer: the players'
+ *  frames, and over them the view bar and the grid's tiles. It takes no press itself: each player's frame and the view
+ *  bar take their own, so the live Scene beneath it is the editor's to orbit and pick. */
+interface StageLayer {
+  readonly host: HTMLDivElement;
+  readonly players: HTMLDivElement;
+  readonly overlay: HTMLDivElement;
+}
+
+let stage: StageLayer | null = null;
+const stageListeners = new Set<() => void>();
+function setStage(next: StageLayer | null): void {
+  stage = next;
+  if (next === null) releaseDocumentLayer(GAME_DOCUMENT);
+  for (const listener of [...stageListeners]) listener();
+}
+function subscribeStage(listener: () => void): () => void {
+  stageListeners.add(listener);
+  return () => { stageListeners.delete(listener); };
+}
+
+function makeStage(): StageLayer {
+  const host = documentLayer(GAME_DOCUMENT);
+  host.dataset['testid'] = 'game-stage';
+  const players = document.createElement('div');
+  Object.assign(players.style, { position: 'absolute', inset: '0', pointerEvents: 'none' });
+  const overlay = document.createElement('div');
+  Object.assign(overlay.style, { position: 'absolute', inset: '0', pointerEvents: 'none' });
+  host.replaceChildren(players, overlay);
+  return { host, players, overlay };
+}
+
+/** Where the live Scene stands in the Game view, as the run places it (`GameStage.scene`). */
+let sceneArea: StdTileBox | 'whole' | null = null;
+const sceneListeners = new Set<() => void>();
+function placeScene(area: StdTileBox | 'whole' | null): void {
+  if (JSON.stringify(area) === JSON.stringify(sceneArea)) return;
+  sceneArea = area;
+  for (const listener of [...sceneListeners]) listener();
+}
+function subscribeSceneArea(listener: () => void): () => void {
+  sceneListeners.add(listener);
+  return () => { sceneListeners.delete(listener); };
+}
+
+/** The Game view: the run's stage over its box, the live Scene where the run places it (the current level's view,
+ *  live, `std-level.document.tsx`, mounted for the run's whole life so its camera stays), and what the run says. */
+function GameView({ active }: { readonly active: boolean }) {
+  const box = useRef<HTMLDivElement | null>(null);
+  const held = useSyncExternalStore(subscribeStage, () => stage, () => null);
+  const area = useSyncExternalStore(subscribeSceneArea, () => sceneArea, () => null);
+  const level = useSyncExternalStore(subscribeCurrentStdLevel, currentStdLevel, () => null);
+  const playing = useSyncExternalStore(subscribeGame, gamePlaying, () => false);
+  const failure = useSyncExternalStore(subscribeGameClock, () => gameClock().failure, () => null);
+  const running = useSyncExternalStore(subscribeGameClock, () => gameClock().running, () => false);
+  useSyncExternalStore(subscribeStdRun, stdRunVersion, stdRunVersion);
+  useLayoutEffect(() => {
+    if (!active || held === null || box.current === null) return undefined;
+    return claimDocumentLayer(GAME_DOCUMENT, box.current);
+  }, [active, held]);
+  // (the play frame `capture --region play` takes, `editor-chrome-capture.ts`: the viewed player's page in the stage, or
+  // the Scene; Grid shows several, and names none)
+  const view = stdRun()?.view;
+  useLayoutEffect(() => {
+    if (held === null) return;
+    if (typeof view === 'number') held.host.dataset['volterPlayFrame'] = '';
+    else delete held.host.dataset['volterPlayFrame'];
+  }, [held, view]);
+  const said = !playing ? 'Stopped: press Play in the Game panel.' : failure;
+  useProgress(playing && !failure && !running ? { documentId: GAME_DOCUMENT, title: 'Starting the game' } : null);
+  const sceneBox: CSSProperties = area === null ? { inset: 0, visibility: 'hidden' } : area === 'whole' ? { inset: 0 } : {
+    left: `${area.left * 100}%`, top: `${area.top * 100}%`, width: `${area.width * 100}%`, height: `${area.height * 100}%`,
+  };
+  return (
+    <div ref={box} data-testid="game-view" style={{ position: 'absolute', inset: 0, background: themeVars.surface.inset }}>
+      {playing && (
+        <div data-testid="game-view-scene" {...(view === 'scene' ? { 'data-volter-play-frame': '' } : {})}
+          style={{ position: 'absolute', ...sceneBox, display: 'flex', flexDirection: 'column' }}>
+          {level === null
+            ? <StateSurface fill title="Open a level to see it here, live." />
+            : <StdLevelView documentId={SCENE_VIEW} level={level.path} label={level.label} live />}
+        </div>
+      )}
+      {said !== null && <StateSurface fill tone={playing ? 'error' : 'neutral'} title={said} style={{ pointerEvents: 'none' }} />}
+    </div>
+  );
+}
+
+/** What runs the game in a stage, as play's page half runs it (`play.page.tsx`): the answer stops it. */
+export type GameRunner = (stage: GameStage) => () => void;
+
+/** Whether the Game view holds the keyboard: it is the document in front, and the focus is the page's own, in the
+ *  Game view (its box or its layer), or the pane that holds the Game view alone, never another part of the workbench. */
+function gameViewHasKeys(): boolean {
+  const shown = claimedBox(GAME_DOCUMENT);
+  if (activeWorkspaceDocumentId() !== GAME_DOCUMENT || shown === null) return false;
+  const focused = document.activeElement;
+  if (focused === null || focused === document.body) return true;
+  if (shown.contains(focused) || (documentLayerOf(GAME_DOCUMENT)?.contains(focused) ?? false)) return true;
+  // (a pane parks the documents behind its tab, unseen: the one it shows is the Game view)
+  const seen = [...focused.querySelectorAll<HTMLElement>('[data-volter-document]')].filter((one) => one.checkVisibility());
+  return focused.contains(shown) && seen.length === 1;
+}
+
+/** The Game view brought to the front while the game runs (`play` asked of a game already playing), as Play brings it
+ *  there as the run starts; nothing while the game has no Game view. */
+export function showGameView(): void {
+  if (openWorkspaceDocuments().some((open) => open.descriptor.id === GAME_DOCUMENT)) activateWorkspaceDocument(GAME_DOCUMENT);
+}
+
+/**
+ * THE PROJECT'S RUN, kept while play is active: Play opens the Game view and runs the game in its stage, a Restart runs
+ * it again, and Stop (or the Game view closed) ends it and brings back the tab that was in front.
+ */
+export function keepGameRuns(run: GameRunner): () => void {
+  let stop: (() => void) | null = null;
+  let generation = -1;
+  let before: string | null = null;
+  const view = (): boolean => openWorkspaceDocuments().some((open) => open.descriptor.id === GAME_DOCUMENT);
+  const sync = (): void => {
+    const playing = gamePlaying();
+    const now = gameGeneration();
+    if (playing && (stop === null || generation !== now)) {
+      stop?.();
+      stop = null;
+      generation = now;
+      if (!view()) {
+        const front = activeWorkspaceDocumentId();
+        before = front === GAME_DOCUMENT ? before : front;
+        openWorkspaceDocument({
+          id: GAME_DOCUMENT,
+          title: 'Game',
+          kind: 'tool-contribution',
+          Content: GameView,
+          // (the Game view closed is the game stopped)
+          onDispose: () => { if (gamePlaying()) setGamePlaying(false); },
+          // (the Hierarchy and the Inspector in every view are the running level's, its Scene's copy, as Unity's
+          // Hierarchy shows the running scene whichever view is focused: `docs/adr/std-scene-view.md`, decision 8)
+          selection: () => workspaceDocumentSelection(SCENE_VIEW),
+        });
+      } else activateWorkspaceDocument(GAME_DOCUMENT);
+      if (stage === null) setStage(makeStage());
+      const { players, overlay } = stage!;
+      stop = run({
+        container: players,
+        overlay,
+        report: (title, detail) => editorHost().console.error(`${title}: ${detail}`, 'play'),
+        keys: gameViewHasKeys,
+        scene: placeScene,
+        // (the stage's layer laid over the Game view's box, in a page that is seen: its players' pages draw)
+        shown: () => document.visibilityState !== 'hidden' && claimedBox(GAME_DOCUMENT) !== null,
+      });
+    } else if (!playing && stop !== null) {
+      stop();
+      stop = null;
+      placeScene(null);
+      setStage(null);
+      const back = before;
+      before = null;
+      if (view()) closeWorkspaceDocument(GAME_DOCUMENT);
+      if (back !== null) activateWorkspaceDocument(back);
+    }
+  };
+  const unsubscribe = subscribeGame(sync);
+  // (the host hears that the Game view is the document that plays, and whether it is paused: its status line says so)
+  setDocumentPlaySignal('play', {
+    state: (documentId) => (documentId !== GAME_DOCUMENT || !gamePlaying() ? 'stopped' : gameClock().paused ? 'paused' : 'playing'),
+    subscribe: (listener) => {
+      const stopRun = subscribeGame(listener), stopClock = subscribeGameClock(listener);
+      return () => { stopRun(); stopClock(); };
+    },
+  });
+  sync();
+  return () => {
+    unsubscribe();
+    setDocumentPlaySignal('play', null);
+    stop?.();
+    stop = null;
+    if (view()) closeWorkspaceDocument(GAME_DOCUMENT);
+    setStage(null);
+  };
+}

package/src/play-clock.ts

@@ -1,7 +1,7 @@
 /**
  * THE GAME PANEL'S CLOCK, READ AT TWO RATES (`../contributions/game-panel.tsx`).
  *
- * The Play tool announces its clock every frame, and one changed text node in the workbench's
+ * The run announces its clock every frame, and one changed text node in the workbench's
  * document repaints and re-layerizes the page around it (about 4 ms a frame measured), so the
  * panel does not re-render on every announcement.
  *
@@ -10,7 +10,7 @@
  * {@link CLOCK_TEXT_INTERVAL_MS} apart. The text's last change always lands (a trailing update),
  * so a paused game's step or a stop reads exactly.
  */
-import type { DocumentPlayClock } from '@volter/editor-blender/api';
+import type { GameClock } from './game-run';
 
 /** The clock text's update period: ten times a second, faster than its hundredths can be read. */
 export const CLOCK_TEXT_INTERVAL_MS = 100;
@@ -46,11 +46,11 @@ export function throttledSubscription(
 }
 
 /** The clock's state without its time: what the panel's controls and status line read. */
-export type ClockState = Pick<DocumentPlayClock, 'paused' | 'speed' | 'failure' | 'running'>;
+export type ClockState = Pick<GameClock, 'paused' | 'speed' | 'failure' | 'running'>;
 
 /** A snapshot reader for {@link ClockState} that answers the SAME object until a field changes, so
  *  `useSyncExternalStore` re-renders only on a change of state, not on every tick. */
-export function clockStateReader(read: () => DocumentPlayClock): () => ClockState {
+export function clockStateReader(read: () => GameClock): () => ClockState {
   let held: ClockState | null = null;
   return () => {
     const clock = read();