@volter/editor-blender 0.1.151 → 0.1.152

package/package.json

@@ -3,7 +3,7 @@
   "publisher": "volter",
   "author": "Volter AI, Inc.",
   "license": "AGPL-3.0-only AND GPL-3.0-or-later",
-  "version": "0.1.151",
+  "version": "0.1.152",
   "engines": {
     "vscode": "*"
   },
@@ -95,8 +95,20 @@
       ],
       "views": {
         "statusbar": [
-          "./contributions/blender-version.status.tsx",
-          "./contributions/blender.status.tsx"
+          {
+            "id": "version",
+            "name": "Version",
+            "alignment": "right",
+            "priority": -5998,
+            "module": "./contributions/blender-version.status.tsx"
+          },
+          {
+            "id": "mouseHints",
+            "name": "Mouse hints",
+            "alignment": "left",
+            "priority": 5000,
+            "module": "./contributions/blender.status.tsx"
+          }
         ]
       },
       "finders": [
@@ -535,179 +547,179 @@
       {
         "command": "volter.edit.duplicate",
         "key": "shift+D",
-        "when": "volter.focused && !inputFocus && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.focused && !inputFocus && volter.keymap == 'blender'"
       },
       {
         "command": "volter.edit.selectAll",
         "key": "A",
-        "when": "volter.focused && !inputFocus && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.focused && !inputFocus && volter.keymap == 'blender'"
       },
       {
         "command": "volter.edit.deselectAll",
         "key": "alt+A",
-        "when": "volter.focused && !inputFocus && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.focused && !inputFocus && volter.keymap == 'blender'"
       },
       {
         "command": "volter.edit.delete",
         "key": "X",
-        "when": "volter.focused && !inputFocus && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.focused && !inputFocus && volter.keymap == 'blender'"
       },
       {
         "command": "volter.transform.select",
         "key": "W",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.transform.translate",
         "key": "G",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.transform.rotate",
         "key": "R",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.transform.scale",
         "key": "S",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.viewport.frameSelection",
         "key": "NumPad_Decimal",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.viewport.frameSelection",
         "key": ".",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.viewport.cyclePivot",
         "key": ",",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.bottom",
         "key": "ctrl+NumPad7",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.back",
         "key": "ctrl+NumPad1",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.left",
         "key": "ctrl+NumPad3",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.orbitLeft",
         "key": "NumPad4",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.orbitRight",
         "key": "NumPad6",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.orbitUp",
         "key": "NumPad8",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.orbitDown",
         "key": "NumPad2",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.opposite",
         "key": "NumPad9",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.rollLeft",
         "key": "shift+NumPad4",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.rollRight",
         "key": "shift+NumPad6",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.all",
         "key": "Home",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.zoomIn",
         "key": "ctrl+=",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.zoomIn",
         "key": "NumPad_Add",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.zoomOut",
         "key": "ctrl+-",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.zoomOut",
         "key": "NumPad_Subtract",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.view.projection",
         "key": "NumPad5",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.unboundKey",
         "key": "ctrl+D",
         "mac": "cmd+D",
-        "when": "volter.focused && !inputFocus && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.focused && !inputFocus && volter.keymap == 'blender'"
       },
       {
         "command": "volter.edit.delete",
         "key": "Delete",
-        "when": "volter.focused && !inputFocus && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.focused && !inputFocus && volter.keymap == 'blender'"
       },
       {
         "command": "volter.unboundKey",
         "key": "Backspace",
-        "when": "volter.focused && !inputFocus && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.focused && !inputFocus && volter.keymap == 'blender'"
       },
       {
         "command": "volter.unboundKey",
         "key": "Q",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.unboundKey",
         "key": "E",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.unboundKey",
         "key": "F",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.keymap == 'blender'"
       },
       {
         "command": "volter.unboundKey",
         "key": "M",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.stage.surface == 'canvas' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.stage.surface == 'canvas' && volter.keymap == 'blender'"
       },
       {
         "command": "volter.unboundKey",
         "key": "ctrl+'",
         "mac": "cmd+'",
-        "when": "volter.stage.focused && volter.stage.mode != 'PLAY' && volter.stage.surface == 'canvas' && volter.keymap == 'blender'"
+        "when": "volter.stage.focused && volter.stage.surface == 'canvas' && volter.keymap == 'blender'"
       }
     ],
     "languageModelTools": [
@@ -1233,17 +1245,17 @@
     }
   },
   "dependencies": {
-    "@volter/editor-movie": "0.5.212",
+    "@volter/editor-movie": "0.5.213",
     "@modelcontextprotocol/sdk": "1.32.1",
-    "@volter/blender-engine": "0.1.149",
-    "@volter/editor-threejs": "0.5.212",
+    "@volter/blender-engine": "0.1.150",
+    "@volter/editor-threejs": "0.5.213",
     "zod": "^4.3.6",
     "@fortawesome/free-solid-svg-icons": "^7.2.0"
   },
   "peerDependencies": {
-    "@volter/live": "0.5.212",
-    "@volter/project": "0.5.212",
-    "@volter/sdk": "0.5.212",
+    "@volter/live": "0.5.213",
+    "@volter/project": "0.5.213",
+    "@volter/sdk": "0.5.213",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "three": "^0.186.1",

package/serving/blender-routes.ts

@@ -90,7 +90,6 @@ export function blenderRoutesPlugin(services: ProjectServingServices): Plugin {
       method: 'GET',
       match: /^\/__editor\/blender-wasm\/status$/,
       handle: async (_req, res) => {
-        services.allowCrossOriginFrameEmbedding(res);
         json(res, await blenderWasmStatus());
       },
     },
@@ -169,10 +168,6 @@ export function blenderRoutesPlugin(services: ProjectServingServices): Plugin {
       match: /^\/__editor\/blender-wasm\/([^/]+)$/,
       handle: async (req, res, url) => {
         const file = decodeURIComponent(url.pathname.slice('/__editor/blender-wasm/'.length));
-        // The frame's page is cross-origin-isolated and this session is not its origin, so every
-        // byte of the engine has to say it may be embedded — the glue above all, which Blender's
-        // pthreads load with `importScripts`.
-        services.allowCrossOriginFrameEmbedding(res);
         const bundled = (BLENDER_WASM_FILES as readonly string[]).includes(file);
         if (!bundled && file !== BLENDER_WALI_ARTIFACT) {
           json(res, { error: `The Blender build has no ${file}.` }, 404);

package/src/api.ts

@@ -1,9 +1,9 @@
 /**
  * EDITOR-BLENDER'S API, AS TYPES: what its page half's `activate` returns
- * (`../contributions/blender.page.ts`), the model Play seam's types and a landed save's. A package that reads the
+ * (`../contributions/blender.page.ts`), the Play tool seam's type and a landed save's. A package that reads the
  * API imports these type-only; the values come from `getExtension(...).exports`.
  */
 export type BlenderPageApi = ReturnType<typeof import('../contributions/blender.page').activate>;
-export type * from './model-play-extension';
+export type { PlayTool } from './play-tool';
 export type { ModelPlayMode } from './play-mode';
 export type { ModelDocumentSaved } from '../host/blender-runtime-host';

package/src/play-mode.ts

@@ -1,8 +1,8 @@
-/** The model’s bottom area shows animation editors or the Play tool’s Game panel. Switching views leaves a run active. Remember the person’s mode per document for this browser session; otherwise use hasScript to choose the default. The Model announces its identity so focusing the bottom-area document does not change the run’s target. */
+/** A model's bottom area shows Blender's animation editors or the Play tool's Game panel; switching leaves a running game running. Remember the person's mode per model for this browser session; otherwise a model opens in Game where the project has a game (`PlayTool.hasGame`). The model on screen announces itself, so focusing the bottom area does not change which model it serves. */
 import {
-  modelPlayExtension,
-  subscribeModelPlayExtension,
-} from './model-play-extension';
+  playTool,
+  subscribePlayTool,
+} from './play-tool';
 
 export type ModelPlayMode = 'game' | 'animation';
 
@@ -13,8 +13,6 @@ export function playModeOf(value: unknown): ModelPlayMode | null {
 
 const STORAGE_PREFIX = 'volter.blender.play-mode:';
 const listeners = new Set<() => void>();
-/** Verbs waiting for a document to be on screen (`documentOnScreen`), told at every change. */
-const waiters = new Set<() => void>();
 /** The person's pick per document; `null` once storage was read and held none. */
 const chosen = new Map<string, ModelPlayMode | null>();
 /** Each model document's `.blend`, as the document reported it. */
@@ -25,7 +23,6 @@ let version = 0;
 function publish(): void {
   version += 1;
   for (const listener of [...listeners]) listener();
-  for (const waiter of [...waiters]) waiter();
 }
 
 function stored(documentId: string): ModelPlayMode | null {
@@ -38,7 +35,7 @@ function stored(documentId: string): ModelPlayMode | null {
 }
 
 /** The person's own pick for a document, or `null` when the default stands. */
-export function chosenPlayMode(documentId: string): ModelPlayMode | null {
+function chosenPlayMode(documentId: string): ModelPlayMode | null {
   let value = chosen.get(documentId);
   if (value === undefined) {
     value = stored(documentId);
@@ -81,57 +78,6 @@ export function servedModelDocument(): string | null {
   return served;
 }
 
-/** Model documents on screen whose file is still opening (read and first presented), the newest last. */
-const opening: string[] = [];
-
-/** An opening Model document does not serve the bottom area until presentation completes. Return its withdrawal function; documentOnScreen waits for it rather than reporting no model. */
-export function noteModelOpening(documentId: string): () => void {
-  opening.push(documentId);
-  publish();
-  return () => {
-    const at = opening.lastIndexOf(documentId);
-    if (at < 0) return;
-    opening.splice(at, 1);
-    publish();
-  };
-}
-
-/** The model document still opening on screen, or `null` with none. */
-export function openingModelDocument(): string | null {
-  return opening.at(-1) ?? null;
-}
-
-/**
- * THE MODEL DOCUMENT ON SCREEN, once it is: the one served now, else the one opening, waited for at most `waitMs`.
- * Answers `{ served }` once one serves the bottom area, `{ opening }` when one is still opening at the end of the wait
- * (the caller asks again: an open can take minutes), and `null` when none is on screen or opening.
- */
-export function documentOnScreen(waitMs: number): Promise<{ readonly served: string } | { readonly opening: string } | null> {
-  const now = (): { readonly served: string } | { readonly opening: string } | null =>
-    served !== null ? { served } : opening.length > 0 ? { opening: opening.at(-1)! } : null;
-  const first = now();
-  if (first === null || 'served' in first || waitMs <= 0) return Promise.resolve(first);
-  return new Promise((resolve) => {
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    const settle = (answer: ReturnType<typeof now>): void => {
-      waiters.delete(check);
-      clearTimeout(timer);
-      clearTimeout(recheck);
-      resolve(answer);
-    };
-    let recheck: ReturnType<typeof setTimeout> | undefined;
-    function check(): void {
-      const answer = now();
-      if (answer !== null && 'served' in answer) { clearTimeout(recheck); settle(answer); return; }
-      // (an opening withdrawn is read again a task later: the document's own commit withdraws it before its
-      // viewport announces itself, both in one commit, and only an open that ended with nothing on screen is none)
-      if (answer === null) { clearTimeout(recheck); recheck = setTimeout(() => { const later = now(); if (later === null || 'served' in later) settle(later); }, 0); }
-    }
-    waiters.add(check);
-    timer = setTimeout(() => settle(now()), waitMs);
-  });
-}
-
 /** The `.blend` a model document reported, if it has a file of its own. */
 export function modelDocumentSource(documentId: string): string | undefined {
   return sources.get(documentId);
@@ -139,17 +85,16 @@ export function modelDocumentSource(documentId: string): string | undefined {
 
 /**
  * THE MODE A DOCUMENT IS IN: Animation whenever no Play tool is installed (there is no game to
- * switch to), else the person's pick, else Game exactly when the level has a game. A
+ * switch to), else the person's pick, else Game exactly when the project has a game. A
  * game not yet looked for counts as none, so a document opens on the Timeline and turns to
  * the Game panel when the answer arrives.
  */
 export function modelPlayMode(documentId: string): ModelPlayMode {
-  const extension = modelPlayExtension();
-  if (extension === null) return 'animation';
+  const tool = playTool();
+  if (tool === null) return 'animation';
   const pick = chosenPlayMode(documentId);
   if (pick !== null) return pick;
-  const blend = sources.get(documentId);
-  return blend !== undefined && extension.hasScript?.(blend) === true ? 'game' : 'animation';
+  return sources.has(documentId) && tool.hasGame() === true ? 'game' : 'animation';
 }
 
 export function playModeVersion(): number {
@@ -169,7 +114,7 @@ export function playModeVersion(): number {
 let stopToolWatch: (() => void) | null = null;
 export function subscribePlayMode(listener: () => void): () => void {
   listeners.add(listener);
-  stopToolWatch ??= subscribeModelPlayExtension(publish);
+  stopToolWatch ??= subscribePlayTool(publish);
   return () => {
     listeners.delete(listener);
     if (listeners.size === 0 && stopToolWatch) {

package/src/play-tool.ts

@@ -0,0 +1,44 @@
+/**
+ * PLAY, THE PROJECT'S, as editor-blender's bottom area shows it (`registerPlay` in its API, `docs/adr/plugin-apis.md`):
+ * a Play tool (play's) owns its run, its controls and its Game view; the bottom area shows the tool's panel under every
+ * document but a model in its Animation mode, and asks the tool whether the project has a game, by which a model opens
+ * in Game or Animation (`play-mode.ts`).
+ */
+import type { ComponentType } from 'react';
+
+export interface PlayTool {
+  /** The run's panel: Play, its transport and its log. */
+  readonly Panel: ComponentType;
+  /** Whether the project has a game to play: `null` while the tool has not looked yet. */
+  hasGame(): boolean | null;
+  /** Every change of what the tool answers. */
+  subscribe(listener: () => void): () => void;
+}
+
+let registered: PlayTool | null = null;
+const listeners = new Set<() => void>();
+function publish(): void { for (const listener of listeners) listener(); }
+
+/** The registered Play tool, or `null` while none is. */
+export function playTool(): PlayTool | null {
+  return registered;
+}
+/** A registration, and every change the registered tool announces. */
+export function subscribePlayTool(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+/** The API's `registerPlay`: one Play tool at a time. */
+export function registerPlay(tool: PlayTool): () => void {
+  if (registered) throw new Error('A Play tool is already registered.');
+  registered = tool;
+  const stop = tool.subscribe(publish);
+  publish();
+  return () => {
+    stop();
+    if (registered !== tool) return;
+    registered = null;
+    publish();
+  };
+}

package/src/model-play-extension.ts

@@ -1,173 +0,0 @@
-/**
- * THE MODEL DOCUMENT'S PLAY, which editor-blender owns and offers in its API (`registerModelPlay`,
- * `docs/adr/plugin-apis.md`). A Play tool owns its controls, state and runner; the model document
- * lends that runner its detached stage. play registers its tool from its own `activate`, through
- * the API; the host hears only whether a document plays (`@volter/sdk/document-play-extension`).
- */
-import { setDocumentPlaySignal } from '@volter/sdk/document-play-extension';
-import type { ComponentType } from 'react';
-
-export interface DocumentPlayControlProps {
-  readonly documentId: string | undefined;
-  readonly onClose: () => void;
-}
-/** Where the document's own area stands while its game runs (`DocumentPlayStage.edit`): a box is in fractions of the
- *  stage. */
-export type DocumentPlayEditArea = 'live' | 'hidden' | { readonly left: number; readonly top: number; readonly width: number; readonly height: number };
-export interface DocumentPlayStage {
-  readonly documentId: string;
-  readonly sourcePath: string;
-  readonly report: (title: string, detail: string) => void;
-  /** Where the tool draws its game, over the document's own area. */
-  readonly container: HTMLElement;
-  /** The game's first frame stands. */
-  readonly ready: () => void;
-  /** THE DOCUMENT'S OWN AREA WHILE THE GAME RUNS ON: `live` brings the editing area back in front, live for editing
-   *  (its keys the editor's); a box shows it drawing in that part of the stage, taking no press (a tile among the
-   *  game's views); `hidden` puts the game in front again. */
-  readonly edit?: (area: DocumentPlayEditArea) => void;
-  /** A layer over the editing area and the play area alike, for the tool's view controls, which stand whichever area
-   *  is in front; it takes no press itself. */
-  readonly overlay?: HTMLElement;
-}
-
-/**
- * A RUNNING GAME'S CLOCK, as the Play tool keeps it: the game's own seconds and frames, which stand still while paused
- * and run at `speed` times the page's own clock otherwise.
- */
-export interface DocumentPlayClock {
-  /** The game's seconds since this run began. */
-  readonly time: number;
-  /** The frames the game has run since this run began. */
-  readonly tick: number;
-  readonly paused: boolean;
-  /** Simulation seconds per real second; one of the transport's `speeds`. */
-  readonly speed: number;
-  /** While playing with no game running because the game failed to start or threw: why. The
-   *  run stays playing (a save of the game retries it); a running game clears it. */
-  readonly failure?: string | null;
-  /** A game has started in this run and is running (its first update ran). False while the run
-   *  is still preparing, and while it plays with a `failure`. 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;
-}
-/**
- * THE GAME'S TRANSPORT — what a Play tool offers beyond Play and Stop, for a layout that draws a
- * game panel (Cyclotron's Game mode, `@volter/editor-blender`). Optional: a tool without
- * one still plays and stops, and a layout draws only the controls a tool answers.
- */
-export interface DocumentPlayTransport {
-  /** The speeds `setSpeed` accepts, slowest first. */
-  readonly speeds: readonly number[];
-  clock(documentId: string): DocumentPlayClock;
-  /** The clock moves every played frame, so it has a subscription of its own: `subscribe` would
-   *  re-render everything that only asks whether a document plays. */
-  subscribeClock(listener: () => void): () => void;
-  /** Hold or release the game; the answer settles once the game has. */
-  setPaused(documentId: string, paused: boolean): void | Promise<void>;
-  /** `frames` frames (one when absent), pausing the game first. */
-  step(documentId: string, frames?: number): void | Promise<void>;
-  setSpeed(documentId: string, speed: number): void | Promise<void>;
-  /** Begin the run again on a FRESH detached copy, the clock at zero. */
-  restart(documentId: string): void;
-  /** Changes on every restart. The document that lends the stage keys its detached copy on it,
-   *  so a new generation is a new copy; the change is announced through `subscribe`. */
-  generation(documentId: string): number;
-  /** Whether the running game's own bot drives the player in view, and the goals it offers; a change is announced
-   *  through `subscribeClock`. Absent, the tool has no autoplay. */
-  autoplay?(documentId: string): DocumentPlayAutoplay;
-  /** Switch the bot on (it must be offered, and the game playing) or off. On plays `goal` (the game's own when
-   *  absent); the answer settles once the goal has started. */
-  setAutoplay?(documentId: string, on: boolean, by: 'panel' | 'cli', goal?: string): void | Promise<void>;
-  /** While stopped, ask the next start to switch the bot on with `goal` as soon as its player joins. Absent, autoplay
-   *  can only be switched while running. */
-  armAutoplay?(documentId: string, armed: boolean, goal?: string): void;
-}
-/**
- * AUTOPLAY, AS THE EDITOR OWNS IT: a game offers a bot and its goals, the editor decides whether it drives the player
- * in view. A person's own press in the game takes it back (`takeover`).
- */
-export interface DocumentPlayAutoplay {
-  readonly on: boolean;
-  /** The bot can be switched on for the player in view. */
-  readonly available: boolean;
-  /** Why the bot cannot be switched on now, in the tool's words (no goals, a view with no player, a player not yet
-   *  joined): the Game panel and `play state` say it. */
-  readonly unavailable?: string | null;
-  /** Who made the last change. */
-  readonly by: 'panel' | 'cli' | 'takeover' | null;
-  /** Armed while stopped (`armAutoplay`): the next start turns it on once its player joins. */
-  readonly armed?: boolean;
-  /** The goals the game's bot offers, and the one driving, armed, or the game's own. */
-  readonly behaviors?: readonly string[];
-  readonly behavior?: string | null;
-  /** A goal played where the person is not looking (a std game's headless play), and how it stands: `<goal>:
-   *  playing`, `<goal>: achieved` or `<goal>: failed — why`; null before any. */
-  readonly state?: string | null;
-}
-export interface DocumentPlayExtension {
-  readonly Control: ComponentType<DocumentPlayControlProps>;
-  readonly Menu: ComponentType<DocumentPlayControlProps>;
-  /** The run's panel, which a document's layout shows in its bottom area while it plays, when the tool has one. */
-  readonly Panel?: ComponentType;
-  playing(documentId: string): boolean;
-  /** Intended live frame shape; absent/null lets the document fill its area. */
-  aspectRatio?(documentId: string): number | null;
-  setPlaying(documentId: string, value: boolean): void;
-  escape?(documentId: string): void;
-  subscribe(listener: () => void): () => void;
-  run(stage: DocumentPlayStage): () => void;
-  /** Pause, step, speed, restart and the clock, when the tool keeps them. */
-  readonly transport?: DocumentPlayTransport;
-  /** What this tool runs to play a document's source file (a game's dev server command). */
-  scriptPath?(sourcePath: string): string;
-  /** Whether the document's source has a game to play: `null` while the tool has not looked yet. A change is announced
-   *  through `subscribe`. A layout uses it to open a document as a game or as a model. */
-  hasScript?(sourcePath: string): boolean | null;
-}
-
-let registered: DocumentPlayExtension | null = null;
-const listeners = new Set<() => void>();
-function publish(): void { for (const listener of listeners) listener(); }
-
-/** The registered Play tool, or `null` while none is. */
-export function modelPlayExtension(): DocumentPlayExtension | null {
-  return registered;
-}
-/** A registration, and every change the registered tool announces. */
-export function subscribeModelPlayExtension(listener: () => void): () => void {
-  listeners.add(listener);
-  return () => { listeners.delete(listener); };
-}
-
-/** Whether a document's Play runs and is paused, for the host. A pause is a clock change, and the
- *  clock moves every played frame, so its subscribers are readers whose snapshot changes rarely. */
-function signal(extension: DocumentPlayExtension) {
-  return {
-    state(documentId: string): 'playing' | 'paused' | 'stopped' {
-      if (!extension.playing(documentId)) return 'stopped';
-      return extension.transport?.clock(documentId).paused ? 'paused' : 'playing';
-    },
-    subscribe(listener: () => void): () => void {
-      const stopPlay = extension.subscribe(listener);
-      const stopClock = extension.transport?.subscribeClock(listener);
-      return () => { stopPlay(); stopClock?.(); };
-    },
-  };
-}
-
-/** The API's `registerModelPlay`: one Play tool for model documents at a time. */
-export function registerModelPlay(extension: DocumentPlayExtension): () => void {
-  if (registered) throw new Error('A Play tool already plays model documents.');
-  registered = extension;
-  const stop = extension.subscribe(publish);
-  setDocumentPlaySignal('model', signal(extension));
-  publish();
-  return () => {
-    stop();
-    if (registered !== extension) return;
-    registered = null;
-    setDocumentPlaySignal('model', null);
-    publish();
-  };
-}