@volter/play 0.5.210 → 0.5.212

package/contributions/model-play.verbs.ts

@@ -0,0 +1,44 @@
+/**
+ * THE MODEL 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.
+ *
+ * `model-play-log`, the read behind `cyclotron play-log` and `editor.contributedVerb('model-play-log')` in `eval`, answers one model
+ * document's play log (`../src/play-log.ts`) — `documentId`'s, or the active Play's when omitted; 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.
+ *
+ * `model-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.model-play.<action>` runs (`game-panel.tsx`), so an agent drives the run the
+ * person sees and answers with the game's state.
+ */
+import type { VerbHandler } from '@volter/sdk/commands';
+import { executeCommand } from '@volter/sdk/editor-commands';
+import { readModelPlayLog } from '../src/play-log';
+
+const ACTIONS = ['state', 'play', 'stop', 'pause', 'resume', 'restart'] as const;
+
+export const modelPlayVerbs: Readonly<Record<string, VerbHandler>> = {
+  'model-play': async (command) => {
+    const action = command['action'];
+    if (typeof action !== 'string' || !(ACTIONS as readonly string[]).includes(action))
+      return { ok: false, error: `model-play's action is one of ${ACTIONS.join(', ')}; it was given ${JSON.stringify(action)}.` };
+    return { ok: true, data: { result: (await executeCommand(`volter.model-play.${action}`, {})) ?? null } };
+  },
+  'model-play-log': (command) => {
+    const since = command['since'];
+    const kind = command['kind'];
+    const documentId = command['documentId'];
+    if (documentId !== undefined && typeof documentId !== 'string')
+      return { ok: false, error: `model-play-log's documentId is a model document id, a string; it was given ${JSON.stringify(documentId)}.` };
+    if (since !== undefined && (typeof since !== 'number' || !Number.isFinite(since)))
+      return { ok: false, error: `model-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: `model-play-log's kind is an entry kind, a string; it was given ${JSON.stringify(kind)}.` };
+    const reading = readModelPlayLog({
+      ...(documentId === undefined ? {} : { documentId }),
+      ...(since === undefined ? {} : { since }),
+      ...(kind === undefined ? {} : { kind }),
+    });
+    return { ok: true, data: { ...reading } };
+  },
+};

package/contributions/play.page.tsx

@@ -0,0 +1,211 @@
+/**
+ * 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`).
+ */
+import { useSyncExternalStore } from 'react';
+import { Button, EditorIcon, editorIcons, MenuItem } from '@volter/sdk/widgets';
+import type { BlenderPageApi, DocumentPlayControlProps, DocumentPlayExtension } 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 { 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:/, '');
+
+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';
+
+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))
+      .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);
+    },
+    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),
+    },
+    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`)
+  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);
+  // 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);
+  context.subscriptions.push({
+    dispose() {
+      unregister();
+      stopStdLevels();
+      stopSceneLevel();
+      keepEditorBlender(null, null);
+      keepEditorThreejs(null);
+    },
+  });
+}

package/contributions/std-scene.document.tsx

@@ -0,0 +1,345 @@
+/**
+ * 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
+ * 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.
+ *
+ * - The level's `<Canvas>` settings are the view's presentation: Rendered shading lit by the scene alone, its backdrop
+ *   the scene's own (the level's sky), its tone mapping the canvas's; its shadows are the renderer's.
+ * - Its view transform (std's shaper and baked LUT) is the stage's display transform; a grading with effects beyond it
+ *   is named in the banner, as the view does not draw them.
+ * - 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.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import * as THREE from 'three';
+import type { DocumentDisplayTransform, ViewportStage } from '@volter/editor-threejs/api';
+import type { ToolContributionProps } from '@volter/sdk/contributions';
+import { projectModuleChangeMatches, subscribeProjectModuleChange } from '@volter/sdk/project-module-changes';
+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';
+
+export const point = 'workspace.document';
+export const title = 'Scene';
+
+/** The level's module, as `../serving/std-scene.ts` writes it. */
+interface StdSceneModule {
+  readonly component: string;
+  readonly canvas: { readonly gl?: { readonly toneMapping?: THREE.ToneMapping; readonly toneMappingExposure?: number } };
+  readonly gradingExtra: boolean;
+  mountScene(args: {
+    readonly renderer: THREE.WebGLRenderer;
+    readonly world: THREE.Scene;
+    readonly camera: THREE.Camera;
+    readonly root: THREE.Group;
+    readonly onError: (error: unknown) => void;
+  }): Promise<MountedScene>;
+  viewTransform(): Promise<(DocumentDisplayTransform & { dispose(): void }) | null>;
+}
+
+interface MountedScene {
+  draw(overlays: boolean): void;
+  advance(seconds: number): void;
+  unmount(): void;
+}
+
+/** The viewport's tone mappers, by three's constant: fiber's own default, a canvas stating none, is ACES. */
+const TONE_MAPPERS = new Map<THREE.ToneMapping, 'none' | 'aces' | 'agx'>([
+  [THREE.NoToneMapping, 'none'],
+  [THREE.ACESFilmicToneMapping, 'aces'],
+  [THREE.AgXToneMapping, 'agx'],
+]);
+
+const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+/** The presentation that draws a level as its canvas does; a string where the canvas asks what the viewport lacks. */
+function canvasPresentation(canvas: StdSceneModule['canvas']): PresentationLayer | string {
+  const toneMapping = canvas.gl?.toneMapping ?? THREE.ACESFilmicToneMapping;
+  const mapper = TONE_MAPPERS.get(toneMapping);
+  if (mapper === undefined) return `The level's canvas tone-maps with three's mapper ${toneMapping}, which the viewport does not draw (it draws none, ACES and AgX).`;
+  return {
+    drawMode: 'rendered',
+    all: {
+      lighting: { source: 'scene', auto: null, tone: { mapper, exposure: canvas.gl?.toneMappingExposure ?? 1 } },
+      backdrop: { source: 'scene' },
+    },
+  };
+}
+
+const MARKER_COLOURS: Readonly<Record<string, number>> = { spawn: 0x4ade80, seat: 0x60a5fa, prompt: 0xfacc15 };
+
+/** A marker's sign on the helper layer: a diamond at the object's origin and its name and behaviours above it. */
+function markerSign(object: THREE.Object3D, behaviours: readonly string[]): THREE.Object3D {
+  const colour = MARKER_COLOURS[behaviours[0] ?? ''] ?? 0xf472b6;
+  const sign = new THREE.Group();
+  const diamond = new THREE.LineSegments(
+    new THREE.EdgesGeometry(new THREE.OctahedronGeometry(0.3)),
+    new THREE.LineBasicMaterial({ color: colour, depthTest: false, transparent: true }),
+  );
+  diamond.renderOrder = 999;
+  const text = `${object.name || '(unnamed)'} · ${behaviours.join(', ')}`;
+  const canvas = document.createElement('canvas');
+  const context = canvas.getContext('2d')!;
+  context.font = '28px Inter, system-ui, sans-serif';
+  canvas.width = Math.ceil(context.measureText(text).width) + 24;
+  canvas.height = 44;
+  context.font = '28px Inter, system-ui, sans-serif';
+  context.fillStyle = 'rgba(0, 0, 0, 0.6)';
+  context.fillRect(0, 0, canvas.width, canvas.height);
+  context.fillStyle = `#${colour.toString(16).padStart(6, '0')}`;
+  context.fillText(text, 12, 31);
+  const texture = new THREE.CanvasTexture(canvas);
+  texture.colorSpace = THREE.SRGBColorSpace;
+  const label = new THREE.Sprite(new THREE.SpriteMaterial({ map: texture, depthTest: false, transparent: true }));
+  label.scale.set((0.4 * canvas.width) / canvas.height, 0.4, 1);
+  label.position.y = 0.6;
+  label.renderOrder = 999;
+  sign.add(diamond, label);
+  return sign;
+}
+
+function disposeSigns(signs: THREE.Object3D): void {
+  signs.traverse((object) => {
+    if (object instanceof THREE.LineSegments) { object.geometry.dispose(); (object.material as THREE.Material).dispose(); }
+    if (object instanceof THREE.Sprite) { object.material.map?.dispose(); object.material.dispose(); }
+  });
+}
+
+/** The std markers under `root`: each object whose `userData.behaviours` names any. */
+function markersOf(root: THREE.Object3D): { readonly object: THREE.Object3D; readonly behaviours: readonly string[] }[] {
+  const found: { object: THREE.Object3D; behaviours: readonly string[] }[] = [];
+  root.traverse((object) => {
+    const behaviours = (object.userData as { behaviours?: unknown }).behaviours;
+    if (behaviours !== null && typeof behaviours === 'object' && Object.keys(behaviours).length > 0) found.push({ object, behaviours: Object.keys(behaviours) });
+  });
+  return found;
+}
+
+/** The marker signs of `root`, kept on the stage's helper layer at each marker's place, made again as the markers change. */
+function followMarkers(stage: ViewportStage, root: THREE.Object3D, shown: () => boolean): () => void {
+  let signature = '';
+  let signs: THREE.Group | null = null;
+  let objects: THREE.Object3D[] = [];
+  const stop = stage.onFrame(() => {
+    if (!shown()) {
+      if (signs) { stage.setHelper('std-markers', null); disposeSigns(signs); signs = null; signature = ''; }
+      return;
+    }
+    const markers = markersOf(root);
+    const next = markers.map(({ object, behaviours }) => `${object.uuid}:${behaviours.join(',')}`).join('|');
+    if (next !== signature) {
+      signature = next;
+      if (signs) disposeSigns(signs);
+      signs = new THREE.Group();
+      signs.name = 'std markers';
+      for (const { object, behaviours } of markers) signs.add(markerSign(object, behaviours));
+      objects = markers.map(({ object }) => object);
+      stage.setHelper('std-markers', signs);
+    }
+    objects.forEach((object, index) => signs!.children[index]!.position.setFromMatrixPosition(object.matrixWorld));
+  });
+  return () => {
+    stop();
+    stage.setHelper('std-markers', null);
+    if (signs) disposeSigns(signs);
+  };
+}
+
+/** What a binding of the level to one stage reads and reports. */
+interface StageBinding {
+  readonly documentId: string;
+  readonly module: StdSceneModule;
+  readonly transform: DocumentDisplayTransform | null;
+  readonly root: THREE.Group;
+  readonly overlays: () => boolean;
+  readonly mounted: (scene: MountedScene, live: boolean) => void;
+  readonly framed: () => void;
+  readonly fail: (error: unknown) => void;
+}
+
+/**
+ * Each canvas's fiber lifetimes, one after another. Fiber keeps one root per canvas, and a root made on a canvas whose
+ * root is closing takes that root over; so a binding makes its root only once the binding before it on that canvas has
+ * ended its own, and the root a binding made is the one it alone ends.
+ */
+const canvasTurns = new WeakMap<HTMLCanvasElement, Promise<void>>();
+function onCanvas(canvas: HTMLCanvasElement, turn: () => Promise<void>): void {
+  const next = (canvasTurns.get(canvas) ?? Promise.resolve()).then(turn);
+  canvasTurns.set(canvas, next.catch(() => {}));
+}
+
+/**
+ * The level drawn on one stage attachment, as one generation: a fiber root on the attachment's renderer, its frames on
+ * the stage's frame, its markers and its view transform. The answer ends the generation; each of its async steps asks
+ * whether it is still current before it draws or installs anything, and the root it made it ends itself, after its
+ * last step. An attachment the stage makes again (a lost context) has another renderer, and is another generation.
+ */
+function bindStage(stage: ViewportStage, binding: StageBinding): () => void {
+  const { documentId, module, transform, root } = binding;
+  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."));
+    return () => {};
+  }
+  const rig = stage.rig();
+  let current = true;
+  let transformed = false;
+  let ended!: () => void;
+  const end = new Promise<void>((resolve) => { ended = resolve; });
+  const hooks: (() => void)[] = [];
+  onCanvas(rig.renderer.domElement, async () => {
+    if (!current) return;
+    let scene: MountedScene;
+    try {
+      scene = await module.mountScene({ renderer: rig.renderer, world, camera: rig.camera, root, onError: binding.fail });
+    } catch (error) {
+      binding.fail(error);
+      return;
+    }
+    // (from here this generation holds the canvas's root, and ends it below, whatever comes)
+    if (current) {
+      scene.draw(binding.overlays());
+      binding.mounted(scene, true);
+      hooks.push(stage.onFrame(() => {
+        scene.advance(performance.now() / 1000);
+        // (the stage's session stands after its rig: the transform and the framing wait for it)
+        if (transform !== null && !transformed) transformed = three.setDisplayTransform(documentId, transform);
+        binding.framed();
+      }));
+      hooks.push(followMarkers(stage, root, binding.overlays));
+    }
+    await end;
+    binding.mounted(scene, false);
+    scene.unmount();
+  });
+  return () => {
+    current = false;
+    for (const hook of hooks.splice(0).reverse()) hook();
+    if (transformed) three.setDisplayTransform(documentId, null);
+    ended();
+  };
+}
+
+export default function StdSceneView({ documentId: given }: ToolContributionProps) {
+  const documentId = given ?? `tool:${STD_SCENE_DOCUMENT}`;
+  useSyncExternalStore(subscribeSceneLevel, sceneLevelVersion, sceneLevelVersion);
+  const level = sceneLevel();
+  const { Object3DDocumentViewport, frameAll } = editorThreejs();
+  const root = useMemo(() => {
+    const group = new THREE.Group();
+    group.name = 'Level';
+    return group;
+  }, []);
+  const build = useCallback(() => ({ root, dispose() {} }), [root]);
+  const [revision, setRevision] = useState(() => beginLiveModuleRevision());
+  const [overlays, setOverlays] = useState(true);
+  const overlaysRef = useRef(overlays);
+  overlaysRef.current = overlays;
+  const [drawn, setDrawn] = useState<{ readonly presentation: PresentationLayer; readonly component: string } | null>(null);
+  const [notes, setNotes] = useState<{ readonly error: string | null; readonly gradingExtra: boolean }>({ error: null, gradingExtra: false });
+  const mounted = useRef<MountedScene | null>(null);
+  /** The level the camera was framed on, once its content first stood. */
+  const framed = useRef<string | null>(null);
+
+  // (the level drawn again as anything its module depends on is written, made or removed: play's serving half reads
+  // that from the session's module graph and names the levels a change reached, `../serving/std-scene.ts`)
+  useEffect(() => {
+    if (level === null) return;
+    return subscribeProjectModuleChange((_changed, affected) => {
+      if (affected?.some((path) => projectModuleChangeMatches(path, level))) setRevision(beginLiveModuleRevision());
+    });
+  }, [level]);
+
+  useEffect(() => {
+    if (level === null) return;
+    const three = editorThreejs();
+    let disposed = false;
+    let transform: (DocumentDisplayTransform & { dispose(): void }) | null = null;
+    let stopStages: (() => void) | null = null;
+    let bound: THREE.WebGLRenderer | null = null;
+    let unbind: (() => void) | null = null;
+    const fail = (error: unknown): void => { if (!disposed) setNotes((now) => ({ ...now, error: `${level}: ${message(error)}` })); };
+    void (async () => {
+      // (`import` is Vite's mark for a module import: without it a path ending `.blend` is not one Vite transforms, and
+      // the request answers 404)
+      const module = (await import(/* @vite-ignore */ `/@volter-std-scene/${level}?import&v=${revision}`)) as StdSceneModule;
+      if (disposed) return;
+      const look = canvasPresentation(module.canvas);
+      if (typeof look === 'string') { fail(new Error(look)); return; }
+      setDrawn((now) => (now?.component === module.component && JSON.stringify(now.presentation) === JSON.stringify(look) ? now : { presentation: look, component: module.component }));
+      setNotes({ error: null, gradingExtra: module.gradingExtra });
+      const made = await module.viewTransform();
+      if (disposed) { made?.dispose(); return; }
+      transform = made;
+      const binding: StageBinding = {
+        documentId, module, transform: made, root, fail,
+        overlays: () => overlaysRef.current,
+        mounted: (scene, live) => {
+          if (live) mounted.current = scene;
+          else if (mounted.current === scene) mounted.current = null;
+        },
+        // (framed once a level, as its content first stands: a draw again keeps the camera)
+        framed: () => {
+          if (framed.current !== level && !new THREE.Box3().setFromObject(root).isEmpty() && frameAll(documentId)) framed.current = level;
+        },
+      };
+      // (the level follows the stage attachment the document has now, known by its renderer: the stage doors are made
+      // again as any stage binds or goes, its attachment made again after a lost context has another renderer)
+      const follow = (): void => {
+        const stage = three.stage(documentId);
+        const renderer = stage?.rig().renderer ?? null;
+        if (renderer === bound) return;
+        unbind?.();
+        unbind = null;
+        bound = renderer;
+        if (stage) unbind = bindStage(stage, binding);
+      };
+      stopStages = three.onStages(follow);
+      follow();
+    })().catch(fail);
+    return () => {
+      disposed = true;
+      stopStages?.();
+      unbind?.();
+      transform?.dispose();
+    };
+  }, [documentId, frameAll, level, revision, root]);
+
+  useEffect(() => { mounted.current?.draw(overlays); }, [overlays]);
+
+  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.
+    </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>
+        <label style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
+          <input type="checkbox" data-testid="std-scene-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>}
+      <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} />
+        )}
+      </div>
+    </div>
+  );
+}