@volter/play 0.5.212 → 0.5.213

package/contributions/levels.finder.ts

@@ -0,0 +1,43 @@
+/**
+ * A STD GAME'S LEVELS AS ITS DOCUMENTS: each level component, `levels/<Name>Level.tsx`, is a document of its own
+ * (`std-level`, drawn by `std-level.document.tsx` as the game draws it), named as its component is less `Level`, as a level is the
+ * document an engine opens. Its source is its record: its own code, or the `levels/<name>.blend` std's export writes
+ * it from, as a model's `.blend` is the source of the component the game places. The project opens on its main level.
+ */
+import { z } from 'zod';
+import { CODE_LEVEL, sceneLevelOf } from '../src/std-level-files';
+
+export const finder = {
+  name: 'stdLevelDocuments',
+  // (paths only: whether a component is a Blender level's is read from the files beside it)
+  reads: 'files',
+  schema: z
+    .object({
+      finder: z.literal('stdLevelDocuments'),
+      include: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe("Project-relative globs of the levels' files (`levels/**/*.tsx`, and `levels/**/*.blend` to know which components a Blender level writes)"),
+    })
+    .strict(),
+  run(_selection: { finder: 'stdLevelDocuments'; include: readonly string[] }, input: { files?: readonly string[] }) {
+    const files = input.files ?? [];
+    const entries = files
+      .filter((path) => CODE_LEVEL.test(path))
+      .map((path) => ({
+        id: `level:${path}`,
+        // (named as an engine names its levels: `MainLevel` is Main)
+        label: CODE_LEVEL.exec(path)?.[1]?.replace(/Level$/, '') ?? path,
+        kind: 'std-level',
+        region: null,
+        authorable: false,
+        reach: { kind: 'root-mount' as const },
+        // (the level's source: a Blender level's `.blend`, else its own code)
+        source: { path: sceneLevelOf(path, files) ?? path },
+      }));
+    // (the project opens on its level, as an engine opens its main level: the game's Main, else the level last worked
+    // on, the files coming newest first)
+    const opened = entries.find((entry) => entry.label === 'Main') ?? entries[0];
+    return { entries, notes: [] as string[], ...(opened === undefined ? {} : { default: opened.id }) };
+  },
+} as const;

package/contributions/play.page.tsx

@@ -1,210 +1,92 @@
 /**
- * PLAY'S PAGE HALF (`contributes.volter.page`, `docs/adr/plugin-apis.md`): the model document's Play tool, registered
- * through editor-blender's API (`registerModelPlay`), which play declares in `extensionDependencies`: every Play runs in
- * the Blender model document's stage, and plays the project's volter-ai/std game, its own dev pages each a player's
- * (`../src/std-game.ts`).
+ * PLAY'S PAGE HALF (`contributes.volter.page`, `docs/adr/plugin-apis.md`): Play, the project's. It registers its Game
+ * panel through editor-blender's API (`registerPlay`, whose bottom area shows it), which play declares in
+ * `extensionDependencies`, and keeps the project's run (`../src/game-view.tsx`): Play runs the project's volter-ai/std
+ * game whatever document is in front, its own dev pages each a player's (`../src/std-game.ts`), in the Game view.
  */
-import { useSyncExternalStore } from 'react';
-import { Button, EditorIcon, editorIcons, MenuItem } from '@volter/sdk/widgets';
-import type { BlenderPageApi, DocumentPlayControlProps, DocumentPlayExtension } from '@volter/editor-blender/api';
+import type { BlenderPageApi, PlayTool } from '@volter/editor-blender/api';
 import { registerVerbCommands, registerViewCommands } from '@volter/sdk/commands';
 import type { PluginContext } from '@volter/sdk/plugins';
-import {
-  armModelPlayAutoplay,
-  MODEL_PLAY_SPEEDS,
-  modelPlayArm,
-  modelPlayClock,
-  modelPlayGeneration,
-  modelPlaying,
-  restartModelPlay,
-  setModelPlayFailure,
-  setModelPlaying,
-  subscribeModelPlay,
-  subscribeModelPlayClock,
-} from '../src/model-play';
-import {
-  isStdGame,
-  runStdGame,
-  stdGameNow,
-  setStdAutoplay,
-  setStdPaused,
-  setStdSpeed,
-  setStdView,
-  STD_DEV,
-  stdAutoplay,
-  stdRun,
-  stepStd,
-  subscribeStdGame,
-  subscribeStdRun,
-} from '../src/std-game';
-import { beginModelPlayLog } from '../src/play-log';
 import { onProjectChange } from '@volter/sdk/active-project';
 import { editorHost } from '@volter/sdk/host';
+import type { ThreePageApi } from '@volter/editor-threejs/api';
+import { setGameFailure, subscribeGame } from '../src/game-run';
+import { keepEditSave, savedEdit } from '../src/game-controls';
+import { type GameRunner, keepGameRuns } from '../src/game-view';
+import { beginPlayLog } from '../src/play-log';
+import { isStdGame, runStdGame, STD_DEV, stdGameNow, subscribeStdGame } from '../src/std-game';
 import { keepEditorBlender } from '../src/editor-blender';
 import { keepEditorThreejs } from '../src/editor-threejs';
-import type { ThreePageApi } from '@volter/editor-threejs/api';
 import { startStdLevels, stdLevelsSettled } from '../src/std-level';
-import { followSceneLevel, openStdScene } from '../src/std-scene-level';
-import { GamePanel, MODEL_PLAY_VIEW_VERBS } from './game-panel';
-import { modelPlayVerbs } from './model-play.verbs';
-
-function usePlaying(documentId: string | undefined): boolean {
-  return useSyncExternalStore(subscribeModelPlay, () => documentId ? modelPlaying(documentId) : false, () => false);
-}
-// Kept because `DocumentPlayExtension` requires `Control` and `Menu` for a layout that draws Play in its header; Cyclotron's layout does not (its Play is the Game panel's).
-function Control({ documentId, onClose }: DocumentPlayControlProps) {
-  const playing = usePlaying(documentId);
-  return <Button size="compact" data-testid="model-play-button" aria-pressed={playing}
-    disabled={!documentId} title={playing ? 'Stop playing (Escape)' : 'Play this level’s game'}
-    onClick={() => { onClose(); if (documentId) setModelPlaying(documentId, !playing); }}>
-    <EditorIcon icon={playing ? editorIcons.transport.stop : editorIcons.transport.play} />
-    {playing ? 'Stop' : 'Play'}
-  </Button>;
-}
-function Menu({ documentId, onClose }: DocumentPlayControlProps) {
-  const playing = usePlaying(documentId);
-  return <MenuItem data-testid="model-play" disabled={!documentId}
-    onSelect={() => { onClose(); if (documentId) setModelPlaying(documentId, !playing); }}>
-    {playing ? 'Stop' : 'Play'}
-  </MenuItem>;
-}
-
-/** The last autoplay state read for a std game's run, and the state it was read over. */
-let autoplaySnapshot: { readonly key: string; readonly value: ReturnType<NonNullable<NonNullable<DocumentPlayExtension['transport']>['autoplay']>> } | null = null;
-/** A model document's level (`document:model:levels/arena.blend` is `levels/arena.blend`). */
-const levelOfDocument = (documentId: string): string => documentId.replace(/^document:model:/, '');
+import { GamePanel, PLAY_VIEW_VERBS } from './game-panel';
+import { playVerbs } from './play.verbs';
 
 const NOT_STD = 'This project is not a std game: it has no std.json, or no @volter-ai/std-dev among its packages (`cyclotron add-play` makes it one).';
 
-function hasScript(): boolean | null {
-  return isStdGame() ?? null;
-}
-
 const EDITOR_BLENDER = 'volter.@volter/editor-blender';
 const EDITOR_THREEJS = 'volter.@volter/editor-threejs';
 
+/** The game run in the Game view's stage, once the edit Play saved first has saved (and exported). */
+const runGame: GameRunner = (stage) => {
+  const failed = (title: string, failure: string) => {
+    const run = beginPlayLog(STD_DEV);
+    run.append('play', 'script-error', { phase: 'stage', message: `${title}: ${failure}` });
+    run.end({ reason: 'stage-failed' });
+    setGameFailure(`${title}: ${failure}`);
+    stage.report(title, failure);
+  };
+  const saved = savedEdit().then((failure) => {
+    if (failure !== null) editorHost().console.warn(`Play's save failed, so the game plays its last export: ${failure}`, 'play');
+  });
+  // (asked now: a project add-play has just made a std game plays without a reload)
+  let stopped = false, stop: (() => void) | null = null;
+  void stdGameNow().then((std) => {
+    if (stopped) return;
+    if (std) stop = runStdGame(stage, failed, saved);
+    else failed('The game could not be started', NOT_STD);
+  });
+  return () => { stopped = true; stop?.(); };
+};
+
 export function activate(context: PluginContext) {
   // Declared in `extensionDependencies`, so it is active before this runs.
   const blender = context.extensions.getExtension<BlenderPageApi>(EDITOR_BLENDER)?.exports;
   if (!blender) throw new Error(`${EDITOR_BLENDER} answered no API.`);
-  /**
-   * PLAY SAVES THE LEVEL FIRST: Play (and Restart) save the open `.blend` where it changed, which runs std's level
-   * export (`../src/std-level.ts`), and the run's pages load once that export has run, so the game plays the current
-   * edit. A save that fails is said in the play log, and the game plays the level as last exported. Play on a prefab's
-   * `.blend` plays the game, its levels as its client draws them, the prefab saved and exported first (the Game panel
-   * says so).
-   */
-  const saves = new Map<string, Promise<string | null>>();
-  const saveLevel = (documentId: string): void => {
-    saves.set(documentId, blender.modelDocument.flush(levelOfDocument(documentId))
+  // (the edit Play saves first: the `.blend` Blender holds, whichever document is in front, and std's export of it)
+  keepEditSave(() => {
+    const held = blender.modelDocument.held();
+    return (held === null ? Promise.resolve() : blender.modelDocument.flush(held))
       .then(() => stdLevelsSettled())
-      .then(() => null, (error: unknown) => error instanceof Error ? error.message : String(error)));
-  };
-  const setPlaying = (documentId: string, value: boolean): void => {
-    if (value && !modelPlaying(documentId)) saveLevel(documentId);
-    setModelPlaying(documentId, value);
-  };
-  const modelPlay: DocumentPlayExtension = {
-    // (the Game panel, which the Blender document's bottom area shows in Game mode, `game-panel.tsx`)
-    Control, Menu, Panel: GamePanel, playing: modelPlaying, setPlaying,
-    // (Escape opens Edit first, its views' way out; from Edit it stops)
-    escape(documentId) {
-      const std = stdRun(documentId);
-      if (std && std.view !== 'edit') setStdView('edit');
-      else setModelPlaying(documentId, false);
-    },
+      .then(() => null, (error: unknown) => error instanceof Error ? error.message : String(error));
+  });
+  const tool: PlayTool = {
+    Panel: GamePanel,
+    hasGame: () => isStdGame() ?? null,
     subscribe(listener) {
-      const stopPlay = subscribeModelPlay(listener), stopProject = onProjectChange(listener), stopStd = subscribeStdGame(listener);
-      return () => { stopPlay(); stopProject(); stopStd(); };
-    },
-    // (the players' pages fit themselves to the stage, which the view bar's tiles and the document's own area share)
-    aspectRatio: () => null,
-    run(stage) {
-      const failed = (title: string, failure: string) => {
-        const run = beginModelPlayLog(stage.documentId, STD_DEV);
-        run.append('play', 'script-error', { phase: 'stage', message: `${title}: ${failure}` });
-        run.end({ reason: 'stage-failed' });
-        setModelPlayFailure(stage.documentId, `${title}: ${failure}`);
-        stage.report(title, failure);
-      };
-      const saved = (saves.get(stage.documentId) ?? Promise.resolve(null)).then((failure) => {
-        saves.delete(stage.documentId);
-        if (failure !== null) editorHost().console.warn(`Play's save of ${stage.sourcePath} failed, so the game plays its last export: ${failure}`, 'model-play');
-      });
-      // (asked now: a project add-play has just made a std game plays without a reload)
-      let stopped = false, stop: (() => void) | null = null;
-      void stdGameNow().then((std) => {
-        if (stopped) return;
-        if (std) stop = runStdGame(stage, failed, saved);
-        else failed('The game could not be started', NOT_STD);
-      });
-      return () => { stopped = true; stop?.(); };
-    },
-    // THE RUN'S TRANSPORT (`model-play.ts`), each control std's own (`../src/std-controls.ts`).
-    transport: {
-      speeds: MODEL_PLAY_SPEEDS,
-      clock: modelPlayClock,
-      // (Autoplay is the viewed player's bot, announced with its run)
-      subscribeClock(listener) {
-        const stopClock = subscribeModelPlayClock(listener), stopStd = subscribeStdRun(listener);
-        return () => { stopClock(); stopStd(); };
-      },
-      setPaused: (documentId, paused) => setStdPaused(documentId, paused).then(() => {}),
-      step: (documentId, frames = 1) => stepStd(documentId, frames).then(() => {}),
-      setSpeed: setStdSpeed,
-      restart: (documentId) => {
-        if (modelPlaying(documentId)) saveLevel(documentId);
-        restartModelPlay(documentId);
-      },
-      generation: modelPlayGeneration,
-      autoplay: (documentId) => {
-        const arm = modelPlayArm(documentId);
-        const running = stdRun(documentId) !== null;
-        const { on, goal, goals, unavailable, headless } = stdAutoplay();
-        const value = {
-          on: running && on,
-          available: running ? unavailable === null : arm === null && goals.length > 0,
-          unavailable: running ? unavailable : null,
-          by: null,
-          armed: arm !== null,
-          behaviors: goals,
-          behavior: arm !== null ? arm.goal ?? goal : goal,
-          state: headless === null ? null
-            : `${headless.goal}: ${headless.state === 'failed' ? `failed — ${headless.why ?? 'std did not say why'}` : headless.state}`,
-        };
-        // (one snapshot until its state changes: the Game panel reads it as an external store)
-        const key = JSON.stringify(value);
-        if (autoplaySnapshot?.key !== key) autoplaySnapshot = { key, value };
-        return autoplaySnapshot.value;
-      },
-      setAutoplay: (documentId, on, by, goal) => {
-        if (!stdRun(documentId)) throw new Error(`Nothing is playing in ${documentId}; \`play\` starts it, then \`play autoplay on\`.`);
-        return setStdAutoplay(on, by, goal);
-      },
-      armAutoplay: (documentId, armed, goal) => armModelPlayAutoplay(documentId, armed, goal ?? null),
+      const stopGame = subscribeGame(listener), stopProject = onProjectChange(listener), stopStd = subscribeStdGame(listener);
+      return () => { stopGame(); stopProject(); stopStd(); };
     },
-    scriptPath: () => STD_DEV,
-    hasScript,
   };
-  keepEditorBlender(blender, modelPlay);
-  // (a std level's Scene view draws in editor-threejs's viewport, `std-scene.document.tsx`; declared in `extensionDependencies`)
+  keepEditorBlender(blender);
+  // (a std level in code is drawn in editor-threejs's viewport, `std-level.document.tsx`; declared in `extensionDependencies`)
   const three = context.extensions.getExtension<ThreePageApi>(EDITOR_THREEJS)?.exports;
   if (!three) throw new Error(`${EDITOR_THREEJS} answered no API.`);
   keepEditorThreejs(three);
-  const unregister = blender.registerModelPlay(modelPlay);
+  const unregister = blender.registerPlay(tool);
+  // (the project's run: Play opens the Game view and runs the game there, whatever document is in front)
+  const stopGameRuns = keepGameRuns(runGame);
   // A std game's levels exported on save, and its prefabs a linked asset library (`std-level.ts`).
   const stopStdLevels = startStdLevels(blender);
-  // The Scene view draws the std level whose Blender document was active last (`std-scene-level.ts`).
-  const stopSceneLevel = followSceneLevel();
   // The session verbs and the Game panel's verbs, as the Code-OSS commands package.json declares.
-  registerVerbCommands(context, { ...modelPlayVerbs, 'std-scene': openStdScene });
-  registerViewCommands(context, 'model-play', MODEL_PLAY_VIEW_VERBS);
+  registerVerbCommands(context, playVerbs);
+  registerViewCommands(context, 'play', PLAY_VIEW_VERBS);
   context.subscriptions.push({
     dispose() {
+      stopGameRuns();
       unregister();
       stopStdLevels();
-      stopSceneLevel();
-      keepEditorBlender(null, null);
+      keepEditSave(null);
+      keepEditorBlender(null);
       keepEditorThreejs(null);
     },
   });

package/contributions/play.verbs.ts

@@ -0,0 +1,74 @@
+/**
+ * THE PLAY VERBS of the session wire (`@volter/sdk/commands`): each the Code-OSS command `volter.<verb>`, registered by
+ * play's page half (`play.page.tsx`), with its budget on its `contributes.commands` entry.
+ *
+ * `play-log`, the read behind `cyclotron play-log` and `editor.contributedVerb('play-log')` in `eval`, answers the game's
+ * play log (`../src/play-log.ts`) — the current run's, or the last one's after Stop — filtered by `since` (game seconds,
+ * inclusive) and `kind`. A read only: no play gate, since an empty log is the honest answer when nothing has played.
+ *
+ * `play`, the agent's tool for Play (declared in this package's `contributes.languageModelTools`), runs the Game panel's
+ * own view verbs, the ones `volter.play.<action>` runs (`game-panel.tsx`), so an agent drives the run the person sees
+ * and answers with the game's state. Its `play` and `restart` answer as `cyclotron play play` does: once a player's page
+ * has joined the run, or with why the game didn't start (`started`), never at "playing" alone.
+ */
+import type { VerbHandler } from '@volter/sdk/commands';
+import { executeCommand } from '@volter/sdk/editor-commands';
+import { readPlayLog } from '../src/play-log';
+import { gameClock, gamePlaying, subscribeGame, subscribeGameClock } from '../src/game-run';
+
+const ACTIONS = ['state', 'play', 'stop', 'pause', 'resume', 'restart'] as const;
+
+/** The actions that start a run, which answer once it runs. */
+const STARTS: ReadonlySet<string> = new Set(['play', 'restart']);
+
+/**
+ * THE RUN STARTED, OR WHY NOT: resolved once a player's page has joined it (`GameClock.running`), rejected with the
+ * run's failure or with Play switched off first, as the CLI's `play` reads the run. No deadline of its own: the run
+ * starts on drawn frames, which a hidden tab doesn't draw, so a healthy start can take as long as the tab stays hidden;
+ * a relayed call (`eval`, the limited view) ends at `volter.play`'s budget, its `timeoutMs`.
+ */
+function started(): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const stops: (() => void)[] = [];
+    const settle = (): void => {
+      const clock = gameClock();
+      const failure = clock.failure !== null && clock.failure !== '' ? clock.failure : null;
+      if (failure === null && gamePlaying() && !clock.running) return;
+      for (const stop of stops) stop();
+      if (failure !== null) reject(new Error(`Play did not start: ${failure}. The play log has the entry (play-log, kind script-error).`));
+      else if (!gamePlaying()) reject(new Error('Play switched itself off before a game started.'));
+      else resolve();
+    };
+    stops.push(subscribeGame(settle), subscribeGameClock(settle));
+    settle();
+  });
+}
+
+export const playVerbs: Readonly<Record<string, VerbHandler>> = {
+  play: async (command) => {
+    const action = command['action'];
+    if (typeof action !== 'string' || !(ACTIONS as readonly string[]).includes(action))
+      return { ok: false, error: `play's action is one of ${ACTIONS.join(', ')}; it was given ${JSON.stringify(action)}.` };
+    const answer = await executeCommand(`volter.play.${action}`, {});
+    if (!STARTS.has(action)) return { ok: true, data: { result: answer ?? null } };
+    try {
+      await started();
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    return { ok: true, data: { result: (await executeCommand('volter.play.state', {})) ?? null } };
+  },
+  'play-log': (command) => {
+    const since = command['since'];
+    const kind = command['kind'];
+    if (since !== undefined && (typeof since !== 'number' || !Number.isFinite(since)))
+      return { ok: false, error: `play-log's since is game seconds, a number; it was given ${JSON.stringify(since)}.` };
+    if (kind !== undefined && typeof kind !== 'string')
+      return { ok: false, error: `play-log's kind is an entry kind, a string; it was given ${JSON.stringify(kind)}.` };
+    const reading = readPlayLog({
+      ...(since === undefined ? {} : { since }),
+      ...(kind === undefined ? {} : { kind }),
+    });
+    return { ok: true, data: { ...reading } };
+  },
+};

package/contributions/{std-scene.document.tsx → std-level.document.tsx}

@@ -1,8 +1,10 @@
 /**
- * A STD GAME'S SCENE VIEW (`docs/adr/std-scene-view.md`): the level whose Blender document was active last
- * (`../src/std-scene-level.ts`), drawn as the game draws it, by its own generated component and the game's own React Three
- * Fiber, react-three-rapier and std, in editor-threejs's viewport (`ThreePageApi`): orbit, pick, frame, the Hierarchy.
- * The level's module is `/@volter-std-scene/<levels/name.blend>` (`../serving/std-scene.ts`); its fiber root draws on
+ * A STD GAME'S LEVEL AS ITS DOCUMENT (`docs/adr/std-scene-view.md`): `levels/<Name>Level.tsx`, a document of the
+ * project's table (`levels.finder.ts`) whose source is its code or the `.blend` std's export writes it from, drawn as
+ * the game draws it, by its own component and the game's own React
+ * Three Fiber, react-three-rapier and std, in editor-threejs's viewport (`ThreePageApi`): orbit, pick, frame, the
+ * Hierarchy.
+ * The level's module is `/@volter-std-scene/<level>` (`../serving/std-scene.ts`); its fiber root draws on
  * the stage's own renderer and camera, the stage drawing the picture, the level's `useFrame`s run on the stage's frame,
  * and its environment is the document's World (editor-threejs's `documentWorld`). The level follows the stage the
  * document has now: an attachment the stage makes again (after a lost context) is bound anew.
@@ -14,8 +16,9 @@
  * - The overlays: colliders and sensors as react-three-rapier's debug lines of the paused world, and each std marker (an
  *   object whose `userData.behaviours` names its behaviours: a spawn point, a seat, a prompt) as a marker and its name,
  *   on the stage's helper layer (`std-markers`). The toolbar's Overlays shows or hides them.
- * - The `.blend` is the source of record: the view edits nothing. Each save exports the level again (`../src/std-level.ts`)
- *   and the view draws it again as anything its module depends on changes, the camera kept.
+ * - The level's source is its record, a Blender level's `.blend` or a level's code: the view edits nothing. A Blender
+ *   level's save exports it again (`../src/std-level.ts`), a code level's file is its own, and the view draws it again
+ *   as anything its module depends on changes (a model a code level places among them), the camera kept.
  */
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
 import * as THREE from 'three';
@@ -25,10 +28,13 @@ import { projectModuleChangeMatches, subscribeProjectModuleChange } from '@volte
 import { beginLiveModuleRevision } from '@volter/sdk/project-module-url';
 import type { PresentationLayer } from '@volter/sdk/viewport-presentation';
 import { editorThreejs } from '../src/editor-threejs';
-import { sceneLevel, sceneLevelVersion, STD_SCENE_DOCUMENT, subscribeSceneLevel } from '../src/std-scene-level';
+import { askPlay } from '../src/std-controls';
+import { stdRun, stdRunVersion, subscribeStdRun } from '../src/std-game';
 
 export const point = 'workspace.document';
-export const title = 'Scene';
+export const title = 'Level';
+/** The editor of the table's `std-level` documents: a level in code (`levels.finder.ts`). */
+export const documentKind = 'std-level';
 
 /** The level's module, as `../serving/std-scene.ts` writes it. */
 interface StdSceneModule {
@@ -48,6 +54,8 @@ interface StdSceneModule {
 interface MountedScene {
   draw(overlays: boolean): void;
   advance(seconds: number): void;
+  /** A change of the game's running scene, put on this copy of the level at its next frame ({@link useRunningScene}). */
+  running(read: SceneRead): void;
   unmount(): void;
 }
 
@@ -187,7 +195,7 @@ function bindStage(stage: ViewportStage, binding: StageBinding): () => void {
   const three = editorThreejs();
   const world = three.documentWorld(root);
   if (world === null) {
-    binding.fail(new Error("The Scene view's root stands in no document scene of its stage."));
+    binding.fail(new Error("The level's root stands in no document scene of its stage."));
     return () => {};
   }
   const rig = stage.rig();
@@ -229,10 +237,42 @@ function bindStage(stage: ViewportStage, binding: StageBinding): () => void {
   };
 }
 
-export default function StdSceneView({ documentId: given }: ToolContributionProps) {
-  const documentId = given ?? `tool:${STD_SCENE_DOCUMENT}`;
-  useSyncExternalStore(subscribeSceneLevel, sceneLevelVersion, sceneLevelVersion);
-  const level = sceneLevel();
+export default function StdLevelDocument({ documentId: given, document, active }: ToolContributionProps) {
+  const level = document?.source?.path ?? null;
+  const documentId = given ?? `level:${level ?? ''}`;
+  // (the level in front last is the current level, which the Game view's Scene shows live)
+  useEffect(() => (active !== false && level !== null ? noteCurrentLevel(level, document?.label ?? level) : undefined), [active, level, document?.label]);
+  return <StdLevelView documentId={documentId} level={level} label={document?.label ?? level} live={false} />;
+}
+
+/** THE CURRENT LEVEL: the level document in front last, which the Game view's Scene draws live; null before any. */
+let currentLevel: { readonly path: string; readonly label: string } | null = null;
+const currentListeners = new Set<() => void>();
+function noteCurrentLevel(path: string, label: string): undefined {
+  if (currentLevel?.path !== path || currentLevel.label !== label) {
+    currentLevel = { path, label };
+    for (const listener of [...currentListeners]) listener();
+  }
+  return undefined;
+}
+export const currentStdLevel = (): { readonly path: string; readonly label: string } | null => currentLevel;
+export function subscribeCurrentStdLevel(listener: () => void): () => void {
+  currentListeners.add(listener);
+  return () => { currentListeners.delete(listener); };
+}
+
+/**
+ * A LEVEL'S VIEW: the level drawn as the game draws it, as authored (its document), or LIVE (the Game view's Scene,
+ * `../src/game-view.tsx`), the game's running scene put on this view's own copy of the level ({@link useRunningScene}).
+ * The same view, code and overlays either way.
+ */
+export function StdLevelView({ documentId, level, label, live }: {
+  readonly documentId: string;
+  readonly level: string | null;
+  readonly label: string | null;
+  /** Live, it reads the running scene while the game runs, drawn or not: its copy of the level is the Hierarchy's. */
+  readonly live: boolean;
+}) {
   const { Object3DDocumentViewport, frameAll } = editorThreejs();
   const root = useMemo(() => {
     const group = new THREE.Group();
@@ -316,30 +356,122 @@ export default function StdSceneView({ documentId: given }: ToolContributionProp
 
   useEffect(() => { mounted.current?.draw(overlays); }, [overlays]);
 
+  useRunningScene(live, mounted, useCallback(() => setRevision(beginLiveModuleRevision()), []));
+
   if (level === null) {
-    return <div data-testid="std-scene-empty" style={{ padding: 16, font: '12px Inter, system-ui, sans-serif' }}>
-      No std level to draw: open a level's Blender file (levels/&lt;name&gt;.blend), and its Scene view draws it.
+    return <div data-testid="std-level-empty" style={{ padding: 16, font: '12px Inter, system-ui, sans-serif' }}>
+      This document names no level: a level in code is levels/&lt;Name&gt;Level.tsx.
     </div>;
   }
   const banner = notes.error ?? (notes.gradingExtra ? "The level's grading holds effects beyond its view transform, which this view does not draw: the game shows them." : null);
   return (
     // (filled from the host box, as the editor's other documents are: in an editor group's auto-height content box
     // `height: 100%` resolves to the content's height, which left the stage a strip)
-    <div data-testid="std-scene" style={{ position: 'absolute', inset: 0, display: 'flex', flexDirection: 'column', overflow: 'hidden' }}>
-      <div role="toolbar" aria-label="Scene" style={{ display: 'flex', alignItems: 'center', gap: 8, padding: '2px 8px', font: '11px Inter, system-ui, sans-serif' }}>
-        <span data-testid="std-scene-level">{level}</span>
+    <div data-testid="std-level" style={{ position: 'absolute', inset: 0, display: 'flex', flexDirection: 'column', overflow: 'hidden' }}>
+      <div role="toolbar" aria-label="Level" style={{ display: 'flex', alignItems: 'center', gap: 8, padding: '2px 8px', font: '11px Inter, system-ui, sans-serif' }}>
+        <span data-testid="std-level-path">{level}</span>
         <label style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
-          <input type="checkbox" data-testid="std-scene-overlays" checked={overlays} onChange={(event) => setOverlays(event.currentTarget.checked)} />
+          <input type="checkbox" data-testid="std-level-overlays" checked={overlays} onChange={(event) => setOverlays(event.currentTarget.checked)} />
           Overlays (colliders, sensors, markers)
         </label>
       </div>
-      {banner !== null && <div role={notes.error ? 'alert' : 'status'} data-testid="std-scene-banner" style={{ padding: '4px 8px', font: '11px Inter, system-ui, sans-serif', background: notes.error ? 'rgba(220, 38, 38, 0.25)' : 'rgba(250, 204, 21, 0.2)' }}>{banner}</div>}
+      {banner !== null && <div role={notes.error ? 'alert' : 'status'} data-testid="std-level-banner" style={{ padding: '4px 8px', font: '11px Inter, system-ui, sans-serif', background: notes.error ? 'rgba(220, 38, 38, 0.25)' : 'rgba(250, 204, 21, 0.2)' }}>{banner}</div>}
       <div style={{ position: 'relative', flex: 1, minHeight: 0 }}>
         {drawn !== null && (
-          <Object3DDocumentViewport documentId={documentId} sourcePath={drawn.component} displayName={`Scene: ${level}`} build={build}
-            stageKind="std-scene" presentation={drawn.presentation} />
+          <Object3DDocumentViewport documentId={documentId} sourcePath={drawn.component} displayName={label ?? level} build={build}
+            stageKind={documentKind} presentation={drawn.presentation} />
         )}
       </div>
     </div>
   );
 }
+
+/** One object of the game's running scene as std reads it (room/shared's scene-reading.ts). */
+interface SceneObject {
+  readonly path: string;
+  readonly type: string;
+  readonly x: number; readonly y: number; readonly z: number;
+  readonly qx: number; readonly qy: number; readonly qz: number; readonly qw: number;
+  readonly sx: number; readonly sy: number; readonly sz: number;
+  readonly visible: boolean;
+}
+
+/** What changed in the game's running scene since an earlier reading (`GET /__std/scene`), and where it runs: `room:<id>`
+ *  for the world the server runs, else the device whose page renders it. */
+interface SceneRead {
+  readonly of: string;
+  readonly scene: string;
+  readonly at: number;
+  readonly whole: boolean;
+  readonly objects: readonly SceneObject[];
+  readonly gone: readonly string[];
+}
+
+/** A reading of the running scene, or none (`of: null`) where it runs nowhere yet. */
+type RunningScene = SceneRead | { readonly of: null };
+
+/** How often the running scene is read again while the game runs (ms): one reading at a time. */
+const SCENE_ASK_MS = 50;
+
+/**
+ * A LIVE LEVEL VIEW IS THE PLAYING WORLD while the game runs (the Game view's Scene), as an engine's scene view is
+ * during Play: the game's running scene, read where it runs (std-dev's `/__std/scene`, through Play's serving half),
+ * each change put on the view's own copy of the level by the runtime (`../serving/std-scene-runtime.js`'s
+ * `SceneNodes`), so its picking and overlays are the level view's own. The scene read is the world's authority: the one
+ * the game's server runs, where it runs one, else the one the viewed player's page renders (the first player's while the
+ * view is Scene or Grid), a game of one player's among them. Each reading names the one held, so a new scene, or another
+ * place it runs, answers whole, and so does the first reading of each copy of the level (a run's start, an edit's
+ * remount), which holds none. When the game stops, the level is drawn again as authored.
+ */
+function useRunningScene(live: boolean, mounted: { readonly current: MountedScene | null }, again: () => void): void {
+  useSyncExternalStore(subscribeStdRun, stdRunVersion, stdRunVersion);
+  const running = live && (stdRun()?.url ?? null) !== null;
+  const againRef = useRef(again);
+  againRef.current = again;
+  // (the run over, the level drawn again as authored)
+  useEffect(() => {
+    if (!running) return undefined;
+    return () => { againRef.current(); };
+  }, [running]);
+  useEffect(() => {
+    if (!running) return;
+    let ended = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    /** The reading held: the scene read last, and its `at`. */
+    let last: { readonly scene: string; readonly at: number } = { scene: '', at: 0 };
+    let fed: MountedScene | null = null;
+    // (the viewed player's page, or the first player's: where a game the server runs no world for plays)
+    const viewedDevice = (): string | null => {
+      const run = stdRun();
+      const player = run === null ? undefined : typeof run.view === 'number' ? run.players[run.view] : run.players[0];
+      return player?.device ?? null;
+    };
+    // (the reading held, named to whichever place is read: a place that runs another scene answers it whole)
+    const held = (): string => `scene=${encodeURIComponent(last.scene)}&since=${last.at}&`;
+    const readScene = async (): Promise<RunningScene> => {
+      const server = await askPlay<RunningScene>(`/scene?${held()}`);
+      if (server.of !== null) return server;
+      const device = viewedDevice();
+      if (device === null) return server;
+      return askPlay<RunningScene>(`/scene?${held()}of=${encodeURIComponent(device)}`);
+    };
+    void (async () => {
+      while (!ended) {
+        const copy = mounted.current;
+        // (a new copy holds no scene, which std answers whole: what the game removed before it is hidden on it too)
+        if (copy !== fed) { fed = copy; last = { scene: '', at: 0 }; }
+        const read = copy === null ? null : await readScene().catch(() => null);
+        if (ended) return;
+        if (read !== null && read.of !== null && copy !== null && copy === mounted.current) {
+          last = { scene: read.scene, at: read.at };
+          copy.running(read);
+        }
+        await new Promise<void>((done) => { timer = setTimeout(done, SCENE_ASK_MS); });
+      }
+    })();
+    return () => {
+      ended = true;
+      clearTimeout(timer);
+    };
+  }, [mounted, running]);
+}