@volter/play 0.5.211 → 0.5.212

package/contributions/game-panel.tsx

@@ -0,0 +1,908 @@
+/**
+ * THE GAME PANEL — what the Blender document's bottom area shows in GAME mode (editor-blender's play mode), in place of
+ * the Timeline (owner, 2026-10-06: "In game mode, the bottom panel is replaced with a game
+ * version of something like that. Perhaps that's where the 'autoplay' controls and info will
+ * live instead").
+ *
+ * ## One Play, here
+ *
+ * The confusion it ends was two Plays on one screen: the header's (the level's game) and the
+ * Timeline's (the file's animation). A mode now chooses which one is shown. In Animation mode the
+ * Timeline's transport is the one shown; in Game mode this panel's Play is, and the Timeline is
+ * not mounted. A game started in Game mode keeps running in Animation mode. The 3D viewport's header carries neither (`blender-header-menus.tsx`
+ * is its menus alone). Escape still stops a game, from the stage, as before.
+ *
+ * ## Where it is
+ *
+ * The Blender document's bottom area shows it (`@volter/editor-blender`'s `blender-play-area.tsx`): play registers it
+ * as the model Play's `Panel` (`play.page.tsx`, through editor-blender's API), and the area's own Game | Animation switch and size stay
+ * the area's. It draws with the area's button and the Timeline's widget table.
+ *
+ * ## What it drives is the Play tool's own run
+ *
+ * Every control here is a call on the Play tool's door (`DocumentPlayExtension` and its
+ * `transport`, `@volter/editor-blender/api`), each std's own control said to the game's pages
+ * (`../src/std-controls.ts`): Pause holds the game's own clock, and the clock drawn here is the
+ * one std answered, the game's seconds and frames. The verbs below are the same calls behind
+ * command ids (`volter.model-play.<verb>`), which is how an agent drives exactly what the person
+ * does: `cyclotron play pause`, or `await editor.command('volter.model-play.pause')` under `eval`.
+ *
+ * ## Autoplay is the editor's switch, and the person always wins
+ *
+ * A std game offers its bot's goals (its `autopilot/` program's); whether the bot drives the
+ * player in view, and with which goal, is this panel's toggle (or `volter.model-play.autoplay`).
+ * A person's own key or click in the player's page takes it back on the spot (std's page does
+ * that), so the driver line reads "You're driving". Stopped, pressing Autoplay arms it for the
+ * next start. Where it cannot be switched on, the panel SAYS why, and `play state` carries the
+ * same reason as `autoplay.why`.
+ *
+ * ## The play log, live
+ *
+ * The right of the panel is the run's play log as it is written (the Play tool's `log` door):
+ * the newest entries of this document, newest at the bottom, filtered by kind. It follows the
+ * newest entry until the person scrolls up to read, and follows again once they scroll back to
+ * the bottom.
+ *
+ * ## It is drawn as the Timeline is
+ *
+ * Same area, same header band, the same widget table (`blender-timeline-geometry.ts`), so the
+ * bottom of the screen changes its job and not its family. The pressed speed cell takes the
+ * playhead's blue, which is Blender's own selected-widget colour in the same theme.
+ */
+import type { ViewVerb } from '@volter/sdk/commands';
+import type {
+  DocumentPlayAutoplay,
+  DocumentPlayClock,
+  DocumentPlayExtension,
+  DocumentPlayTransport,
+} from '@volter/editor-blender/api';
+import {
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+import { editorBlender, registeredModelPlay, subscribeRegisteredModelPlay } from '../src/editor-blender';
+import { CLOCK_TEXT_INTERVAL_MS, type ClockState, clockStateReader, throttledSubscription } from '../src/play-clock';
+import { getCurrentProject, onProjectChange } from '@volter/sdk/active-project';
+import { editorHost } from '@volter/sdk/host';
+import { activateWorkspaceDocument } from '@volter/sdk/workspace-document-registry';
+import { captureStdView, isStdGame, stdRun, stdRunVersion, subscribeStdGame, subscribeStdRun } from '../src/std-game';
+import { EXPORT_LABELS, EXPORT_TARGETS, isExportTarget, onStdExport, setExportMenuOpen, startStdExport, stdExport, stdTargets, type ExportTarget, type StdExport } from '../src/std-export';
+
+/** Said where the project is not a std game, whose Play has nothing to run. */
+const NOT_STD = 'This project is not a std game (no std.json): `cyclotron add-play` makes it one.';
+import { subscribeModelPlayLog, tailModelPlayLog } from '../src/play-log';
+
+const STILL: DocumentPlayClock = { time: 0, tick: 0, paused: false, speed: 1, running: false };
+const NO_BOT: DocumentPlayAutoplay = { on: false, available: false, by: null };
+
+function extension(): DocumentPlayExtension | null {
+  return registeredModelPlay();
+}
+
+/** The bottom area's mode and the model document it serves: editor-blender's, through its API. */
+const playMode = () => editorBlender().playMode;
+
+// ---------------------------------------------------------------------------------------------
+// THE VERBS — `volter.model-play.<verb>`, the panel's controls behind command ids.
+// ---------------------------------------------------------------------------------------------
+
+/** Which document a verb acts on: the one it names, else the model document on screen. */
+function verbDocument(args: Record<string, unknown> | undefined): string {
+  const named = args?.['document'];
+  if (typeof named === 'string' && named !== '') return named;
+  const served = playMode().servedModelDocument();
+  if (served === null) throw new Error('No model document is open; open one, or name it with `document`.');
+  return served;
+}
+
+/** How long a verb waits for a model document still opening on screen before it answers that it is still opening
+ *  (well inside the 30 s a workbench command is given; `cyclotron play` asks again). */
+const VERB_OPEN_WAIT_MS = 20_000;
+/** The sentence a verb answers while the model document on screen is still opening; `cyclotron play` reads it. */
+const STILL_OPENING = 'is still opening';
+
+/** The verbs that start a game, which a document plays only on screen: its stage draws the game. */
+const BRINGS_FORWARD = new Set(['play', 'restart']);
+
+/**
+ * A NAMED DOCUMENT IS BROUGHT FORWARD BEFORE IT PLAYS: a game runs in its document's stage, which only the document on
+ * screen draws, so a Play asked of one behind another would wait for a first frame that never comes. An open document
+ * is activated and waited for; one not open is refused, by name.
+ */
+async function broughtForward(documentId: string): Promise<void> {
+  if (playMode().servedModelDocument() === documentId) return;
+  if (!activateWorkspaceDocument(documentId))
+    throw new Error(`${documentId} is not open, so Play cannot bring it forward to play it: open it (\`editor.open('${documentId.replace(/^document:/, '')}')\`), then ask again.`);
+  const bound = Date.now() + VERB_OPEN_WAIT_MS;
+  while (playMode().servedModelDocument() !== documentId) {
+    if (Date.now() > bound)
+      throw new Error(`${documentId} ${STILL_OPENING}: it was brought forward, and Blender is still reading or presenting its file. Ask again.`);
+    await new Promise((done) => setTimeout(done, 100));
+  }
+}
+
+/**
+ * A VERB ACTS ON THE MODEL DOCUMENT ON SCREEN ONCE IT IS ON SCREEN: one still opening (Blender reading or presenting
+ * its file) is waited for, rather than answered "No model document is open" (editor-blender's `noteModelOpening`); `cyclotron play` asks again while it says so.
+ * A verb that starts a game on a named document brings that document forward first ({@link broughtForward}).
+ */
+function waitingForTheDocument(verbs: readonly ViewVerb[]): ViewVerb[] {
+  return verbs.map((verb) => ({
+    ...verb,
+    run: async (args) => {
+      const named = args?.['document'];
+      if (typeof named !== 'string' || named === '') {
+        const found = await playMode().documentOnScreen(VERB_OPEN_WAIT_MS);
+        if (found !== null && 'opening' in found)
+          throw new Error(`${found.opening} ${STILL_OPENING}: Blender is reading or presenting its file, and the Game panel's controls act on it once it is on screen. Ask again.`);
+      } else if (BRINGS_FORWARD.has(verb.id)) await broughtForward(named);
+      return verb.run(args);
+    },
+  }));
+}
+
+function verbExtension(): DocumentPlayExtension & { transport: NonNullable<DocumentPlayExtension['transport']> } {
+  const found = extension();
+  if (found === null)
+    throw new Error('No Play tool is registered for model documents: @volter/play is not active.');
+  if (found.transport === undefined)
+    throw new Error('The registered Play tool has no pause, step, speed or restart.');
+  return found as DocumentPlayExtension & { transport: NonNullable<DocumentPlayExtension['transport']> };
+}
+
+/** THE ONE REPORT every verb answers with — what the panel draws, as data. A control's effect
+ *  lands on the next drawn frame (a step runs there), so read `state` again to see it. */
+function gameState(documentId: string): unknown {
+  const found = extension();
+  const blend = playMode().modelDocumentSource(documentId);
+  return {
+    document: documentId,
+    mode: playMode().modelPlayMode(documentId),
+    playing: found?.playing(documentId) ?? false,
+    script: blend === undefined || found?.scriptPath === undefined ? null : {
+      path: found.scriptPath(blend),
+      exists: found.hasScript?.(blend) ?? null,
+    },
+    clock: found?.transport?.clock(documentId) ?? STILL,
+    speeds: found?.transport?.speeds ?? [],
+    autoplay: autoplayState(documentId),
+    export: stdExport(),
+  };
+}
+
+/** Who drives the player in view: the bot while autoplay is on, else the person. */
+function driverOf(playing: boolean, autoplay: DocumentPlayAutoplay): 'bot' | 'person' | null {
+  if (!playing) return null;
+  return autoplay.on ? 'bot' : 'person';
+}
+
+/** The bot's switch and who drives (`driverOf`), null when nothing plays; `why` says why the bot cannot be switched
+ *  on, null when it can. */
+function autoplayState(documentId: string): unknown {
+  const found = extension();
+  const autoplay = found?.transport?.autoplay?.(documentId) ?? NO_BOT;
+  const playing = found?.playing(documentId) ?? false;
+  const why = autoplayWhy(playing, found?.transport?.clock(documentId) ?? STILL, autoplay);
+  return { ...autoplay, driver: driverOf(playing, autoplay), why };
+}
+
+/**
+ * WHY THE BOT CANNOT BE SWITCHED ON: `not-running` while stopped or still starting (a player's page must have joined),
+ * `game` once it runs and the run says why (`autoplay.unavailable`: no goals, no player in view), null when it can.
+ */
+function autoplayUnavailable(playing: boolean, clock: Pick<DocumentPlayClock, 'failure' | 'running'>, autoplay: DocumentPlayAutoplay): 'not-running' | 'game' | null {
+  if (playing && clock.running && autoplay.available) return null;
+  if (!playing || !clock.running) return 'not-running';
+  return 'game';
+}
+
+/** {@link autoplayUnavailable} as the CLI says it. */
+function autoplayWhy(playing: boolean, clock: Pick<DocumentPlayClock, 'failure' | 'running'>, autoplay: DocumentPlayAutoplay): string | null {
+  switch (autoplayUnavailable(playing, clock, autoplay)) {
+    case null: return null;
+    case 'game': return autoplay.unavailable ?? 'No autoplay for the player in view.';
+    case 'not-running': return !playing
+      ? 'Autoplay is available once the game is running, and nothing is playing; `play` starts it.'
+      : `Autoplay is available once the game is running, and it is not running yet${clock.failure ? `: ${clock.failure}` : '.'}`;
+  }
+}
+
+function requirePlaying(documentId: string, verb: string): void {
+  if (!verbExtension().playing(documentId))
+    throw new Error(`Nothing is playing in ${documentId}, so there is nothing to ${verb}; \`play\` starts it.`);
+}
+
+/** The Game panel's verbs: the Code-OSS commands `volter.model-play.<verb>`, registered by play's page half. */
+export const MODEL_PLAY_VIEW_VERBS: readonly ViewVerb[] = waitingForTheDocument([
+  { id: 'state', run: (args) => gameState(verbDocument(args)) },
+  {
+    id: 'mode',
+    run: (args) => {
+      const documentId = verbDocument(args);
+      const mode = args?.['mode'] ?? args?.['to'];
+      if (mode !== undefined) {
+        const asked = playMode().playModeOf(mode);
+        if (asked === null) throw new Error(`mode is \`game\` or \`animation\`; got ${String(mode)}.`);
+        editorBlender().switchPlayMode(documentId, asked);
+      }
+      return gameState(documentId);
+    },
+  },
+  {
+    id: 'game-mode',
+    run: (args) => { const documentId = verbDocument(args); editorBlender().switchPlayMode(documentId, 'game'); return gameState(documentId); },
+  },
+  {
+    id: 'animation-mode',
+    run: (args) => { const documentId = verbDocument(args); editorBlender().switchPlayMode(documentId, 'animation'); return gameState(documentId); },
+  },
+  {
+    // PLAY IS GAME MODE'S CONTROL, so asking for it puts the document in Game mode: the person
+    // then sees the panel that owns the run an agent started.
+    id: 'play',
+    run: (args) => {
+      const documentId = verbDocument(args);
+      const found = verbExtension();
+      if (playMode().modelPlayMode(documentId) !== 'game') editorBlender().switchPlayMode(documentId, 'game');
+      if (!found.playing(documentId)) found.setPlaying(documentId, true);
+      return gameState(documentId);
+    },
+  },
+  {
+    id: 'stop',
+    run: (args) => {
+      const documentId = verbDocument(args);
+      verbExtension().setPlaying(documentId, false);
+      return gameState(documentId);
+    },
+  },
+  {
+    id: 'pause',
+    run: async (args) => {
+      const documentId = verbDocument(args);
+      requirePlaying(documentId, 'pause');
+      await verbExtension().transport.setPaused(documentId, true);
+      return gameState(documentId);
+    },
+  },
+  {
+    id: 'resume',
+    run: async (args) => {
+      const documentId = verbDocument(args);
+      requirePlaying(documentId, 'resume');
+      await verbExtension().transport.setPaused(documentId, false);
+      return gameState(documentId);
+    },
+  },
+  {
+    // `count` frames of 1/60 s, which std runs (pausing the game first) and answers.
+    id: 'step',
+    run: async (args) => {
+      const documentId = verbDocument(args);
+      requirePlaying(documentId, 'step');
+      const { transport } = verbExtension();
+      const raw = args?.['count'];
+      const count = raw === undefined ? 1 : typeof raw === 'string' && raw.trim() !== '' ? Number(raw) : typeof raw === 'number' ? raw : Number.NaN;
+      if (!Number.isInteger(count) || count < 1 || count > 600) throw new Error(`step's \`count\` is a whole number of frames from 1 to 600; got ${JSON.stringify(raw)}.`);
+      await transport.step(documentId, count);
+      return gameState(documentId);
+    },
+  },
+  {
+    id: 'speed',
+    run: async (args) => {
+      const documentId = verbDocument(args);
+      const { transport } = verbExtension();
+      const raw = args?.['speed'] ?? args?.['to'];
+      const speed = typeof raw === 'string' ? Number(raw.replace(/x$/i, '')) : Number(raw);
+      if (!transport.speeds.includes(speed))
+        throw new Error(`speed is one of ${transport.speeds.join(', ')} (game seconds per real second); got ${JSON.stringify(raw)}.`);
+      await transport.setSpeed(documentId, speed);
+      return gameState(documentId);
+    },
+  },
+  {
+    // THE EDITOR'S AUTOPLAY SWITCH: on plays one of the game's goals (`goal`, the game's own when absent), off hands the
+    // player in view back to the person. Asked from here (an agent's `cli`), the goal is std's own headless play,
+    // which plays whether or not the editor is seen: it answers once the play has started, and `play state`'s
+    // `autoplay.state` and the play log say how it ends.
+    id: 'autoplay',
+    run: async (args) => {
+      const documentId = verbDocument(args);
+      const raw = args?.['on'];
+      const on = raw === true || raw === 'on' || raw === 'true' ? true
+        : raw === false || raw === 'off' || raw === 'false' ? false : undefined;
+      if (on === undefined) throw new Error(`autoplay's \`on\` is true or false (\`play autoplay on [<goal>]|off\`); got ${String(raw)}.`);
+      const goal = typeof args?.['goal'] === 'string' && args['goal'] !== '' ? args['goal'] : undefined;
+      const found = verbExtension();
+      const { transport } = found;
+      if (transport.setAutoplay === undefined)
+        throw new Error('The registered Play tool has no autoplay.');
+      // (refused while nothing plays; the run says its own reasons, a headless play needing no player's page)
+      if (on && !found.playing(documentId)) throw new Error(autoplayWhy(false, transport.clock(documentId), NO_BOT) ?? 'Nothing is playing.');
+      await transport.setAutoplay(documentId, on, 'cli', on ? goal : undefined);
+      return gameState(documentId);
+    },
+  },
+  {
+    id: 'restart',
+    run: (args) => {
+      const documentId = verbDocument(args);
+      const found = verbExtension();
+      if (playMode().modelPlayMode(documentId) !== 'game') editorBlender().switchPlayMode(documentId, 'game');
+      found.transport.restart(documentId);
+      return gameState(documentId);
+    },
+  },
+]).concat([
+  {
+    // THE GAME EXPORTED, as the panel's Export menu does it, the project's and so no document's: `target` web, roblox or
+    // unreal; an engine the game doesn't target refused unless `add` (true) makes it one first, as the menu's "Add
+    // Roblox and export" does. It answers once the export has started with the export and the game's targets; the
+    // panel says how it stands and ends, and the console holds each line std printed. With no `target`, the export as it
+    // stands.
+    id: 'export',
+    run: async (args) => {
+      const target = args?.['target'];
+      const add = args?.['add'];
+      if (add !== undefined && typeof add !== 'boolean') throw new Error(`export's \`add\` is true or false; got ${JSON.stringify(add)}.`);
+      if (target !== undefined) {
+        if (!isExportTarget(target)) throw new Error(`export's \`target\` is one of ${EXPORT_TARGETS.join(', ')}; got ${JSON.stringify(target)}.`);
+        const targets = await stdTargets();
+        if (target !== 'web' && !targets.includes(target) && add !== true)
+          throw new Error(`${EXPORT_LABELS[target]} isn't a target of this game: export it with \`add: true\` to add it first (std target add ${target}), only where the person asked for ${EXPORT_LABELS[target]}.`);
+        startStdExport(target, add === true);
+      }
+      return { export: stdExport(), targets: await stdTargets() };
+    },
+  },
+]);
+
+// ---------------------------------------------------------------------------------------------
+// THE PANEL
+// ---------------------------------------------------------------------------------------------
+
+/** A 12-px mark in the widget's ink, the way the Timeline header draws its transport. */
+function mark(path: string): ReactNode {
+  const { TIMELINE_CHROME } = editorBlender().timelineGeometry;
+  return (
+    <svg width={12} height={12} viewBox="0 0 12 12" aria-hidden="true">
+      <path d={path} fill={TIMELINE_CHROME.widgetText} />
+    </svg>
+  );
+}
+const MARKS = {
+  play: 'M3 2l7 4-7 4z',
+  stop: 'M2.5 2.5h7v7h-7z',
+  pause: 'M3 2h2v8H3zM7 2h2v8H7z',
+  step: 'M10 2H8.5v8H10zM2.5 2v8L7.5 6z',
+  restart: 'M6 1.5V0l3 2.25-3 2.25V3a3 3 0 1 0 3 3h1.5A4.5 4.5 0 1 1 6 1.5z',
+  capture: 'M4 2l1-1h2l1 1h2.5v8h-9V2zM6 8.5a2.25 2.25 0 1 0 0-4.5 2.25 2.25 0 0 0 0 4.5z',
+} as const;
+
+/** Simulation seconds as a clock reads them: `m:ss.ss`, hours only when there are some. */
+function clockText(seconds: number): string {
+  const whole = Math.floor(seconds / 60);
+  const rest = (seconds - whole * 60).toFixed(2).padStart(5, '0');
+  if (whole < 60) return `${whole}:${rest}`;
+  return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, '0')}:${rest}`;
+}
+
+/** The clock as std last answered it, redrawn at most every {@link CLOCK_TEXT_INTERVAL_MS} ms and always after the
+ *  last change (`../src/play-clock.ts`): the game's seconds and frames where it is paused, which a step moves exactly;
+ *  running, its speed, the time being the game's own between answers. */
+function PlayClockText({ documentId, transport }: { documentId: string | null; transport: DocumentPlayTransport | undefined }) {
+  const { TIMELINE_CHROME } = editorBlender().timelineGeometry;
+  const subscribe = useMemo(
+    () => throttledSubscription((listener: () => void) => transport?.subscribeClock(listener) ?? (() => {}), CLOCK_TEXT_INTERVAL_MS),
+    [transport],
+  );
+  const text = useSyncExternalStore(
+    subscribe,
+    () => {
+      const clock = documentId !== null && transport ? transport.clock(documentId) : STILL;
+      const playing = documentId !== null && (registeredModelPlay()?.playing(documentId) ?? false);
+      return !playing ? `stopped · ${speedText(clock.speed)}` : clock.paused ? `${clockText(clock.time)} · frame ${clock.tick}` : `running · ${speedText(clock.speed)}`;
+    },
+    () => `${clockText(0)} · frame 0`,
+  );
+  return (
+    <span
+      data-testid="model-play-clock"
+      style={{ color: TIMELINE_CHROME.widgetText, fontVariantNumeric: 'tabular-nums', whiteSpace: 'nowrap' }}
+    >
+      {text}
+    </span>
+  );
+}
+
+function speedText(speed: number): string {
+  return `${speed}×`;
+}
+
+/** A control's refusal, said in the console under its name. */
+const said = (control: string) => (error: unknown): void =>
+  editorHost().console.error(`${control}: ${error instanceof Error ? error.message : String(error)}`, 'model-play');
+
+export function GamePanel() {
+  const { PlayAreaButton, PlayModeSwitch, timelineGeometry: { HEADER_HEIGHT, TIMELINE_CHROME, TIMELINE_THEME } } = editorBlender();
+  const { subscribePlayMode, playModeVersion } = playMode();
+  useSyncExternalStore(subscribePlayMode, playModeVersion, playModeVersion);
+  const documentId = playMode().servedModelDocument();
+  const found = useSyncExternalStore(subscribeRegisteredModelPlay, extension, () => null);
+  const transport = found?.transport;
+  const playing = documentId !== null && (found?.playing(documentId) ?? false);
+  const subscribeClock = useCallback(
+    (listener: () => void) => transport?.subscribeClock(listener) ?? (() => {}),
+    [transport],
+  );
+  // THE CLOCK'S STATE, not its time (`../src/play-clock.ts`): the panel re-renders when a game is
+  // paused, sped up, fails or starts running, never once a frame; its time is {@link PlayClockText}'s.
+  const readClockState = useMemo(
+    () => clockStateReader(() => (documentId !== null && transport ? transport.clock(documentId) : STILL)),
+    [documentId, transport],
+  );
+  const clock = useSyncExternalStore(subscribeClock, readClockState, () => STILL);
+  // Whether the project is a std game, which Play plays (undefined while the session is asked).
+  const std = useSyncExternalStore(subscribeStdGame, isStdGame, () => undefined);
+  // Its changes are announced with the clock's.
+  const autoplay = useSyncExternalStore(
+    subscribeClock,
+    () => (documentId !== null && transport?.autoplay ? transport.autoplay(documentId) : NO_BOT),
+    () => NO_BOT,
+  );
+  const blend = documentId === null ? undefined : playMode().modelDocumentSource(documentId);
+  const scriptPath = blend === undefined ? null : (found?.scriptPath?.(blend) ?? null);
+  const canPlay = documentId !== null && found !== null;
+  // A PREFAB IS NOT A LEVEL: Play on one plays the game, its levels as its client draws them, the prefab saved (and so
+  // exported) first, as Unity plays the open scene and a prefab is not one.
+  // THE GAME'S NEWEST ERROR, a player's page's (`std-game.ts`): said where the person looks, as the console says each.
+  useSyncExternalStore(subscribeStdRun, stdRunVersion, stdRunVersion);
+  const thrown = playing && documentId !== null ? stdRun(documentId)?.lastError ?? null : null;
+  // (std's headless play of a goal, where it stands: `win: achieved`, `lose: failed — why`)
+  const headlessLine = playing && autoplay.state ? ` · ${autoplay.state}` : '';
+  const prefab = blend !== undefined && blend.startsWith('prefabs/') ? ' · a prefab: Play plays the game\'s levels, this prefab saved first' : '';
+  const status = documentId === null
+    ? 'No model document is open.'
+    : std === false
+      ? NOT_STD
+      : playing && clock.failure
+        // The run plays but no game runs (`DocumentPlayClock.failure`): say so, not "Playing".
+        ? `Not running — ${clock.failure.replace(/\.$/, '')}. Restart (or save the game) to retry, or Stop.${headlessLine}`
+        : playing && thrown !== null
+        ? `Playing — the game threw: ${thrown}${headlessLine}`
+        : playing
+        ? `${clock.paused ? 'Paused' : 'Playing'} ${scriptPath ?? ''}`.trim() + prefab + headlessLine
+        : (scriptPath === null ? 'Stopped.' : `Stopped · Play runs ${scriptPath}`) + prefab;
+  return (
+    <div
+      data-testid="game-panel"
+      data-playing={playing || undefined}
+      data-paused={(playing && clock.paused) || undefined}
+      data-failed={(playing && Boolean(clock.failure)) || undefined}
+      style={{
+        // Filled from the host box, as the Timeline is and for the reason its own comment gives.
+        position: 'absolute',
+        inset: 0,
+        display: 'flex',
+        flexDirection: 'column',
+        overflow: 'hidden',
+        background: TIMELINE_THEME.back,
+        color: TIMELINE_CHROME.text,
+        font: '11px Inter, system-ui, sans-serif',
+      }}
+    >
+      <div
+        style={{
+          height: HEADER_HEIGHT,
+          flex: `0 0 ${HEADER_HEIGHT}px`,
+          display: 'flex',
+          alignItems: 'center',
+          gap: TIMELINE_CHROME.headerGap,
+          padding: TIMELINE_CHROME.headerPadding,
+          background: TIMELINE_THEME.header,
+          borderBottom: `1px solid ${TIMELINE_CHROME.rule}`,
+        }}
+      >
+        <PlayModeSwitch title="Game" />
+        {/* THE TRANSPORT IN THE MIDDLE, between two spacers, where the Timeline centres its own. */}
+        <div style={{ flex: 1 }} />
+        <div style={{ display: 'flex' }} role="group" aria-label="Game transport">
+          <PlayAreaButton
+            testId="model-play-button"
+            label={playing ? 'Stop playing (Escape)' : 'Play this level’s game'}
+            pressed={playing}
+            wide
+            disabled={!canPlay}
+            // The run's state NOW, not the render's: a game can stop between the two (Escape, an
+            // agent's `stop`, a failed script), and a toggle read from a stale render does nothing.
+            onClick={() => { if (documentId !== null && found) found.setPlaying(documentId, !found.playing(documentId)); }}
+          >
+            {mark(playing ? MARKS.stop : MARKS.play)}
+            {playing ? 'Stop' : 'Play'}
+          </PlayAreaButton>
+          {transport && (
+            <>
+              <PlayAreaButton
+                testId="model-play-pause"
+                label={clock.paused ? 'Resume' : 'Pause'}
+                pressed={playing && clock.paused}
+                disabled={!playing}
+                onClick={() => { if (documentId !== null) void Promise.resolve(transport.setPaused(documentId, !transport.clock(documentId).paused)).catch(said('Pause')); }}
+              >
+                {mark(clock.paused ? MARKS.play : MARKS.pause)}
+              </PlayAreaButton>
+              <PlayAreaButton
+                testId="model-play-step"
+                label="Step one frame (pauses first)"
+                disabled={!playing}
+                onClick={() => { if (documentId !== null) void Promise.resolve(transport.step(documentId)).catch(said('Step')); }}
+              >
+                {mark(MARKS.step)}
+              </PlayAreaButton>
+              <PlayAreaButton
+                testId="model-play-restart"
+                label="Restart: the level saved, every player's page loaded again"
+                disabled={!playing}
+                onClick={() => { if (documentId !== null) transport.restart(documentId); }}
+              >
+                {mark(MARKS.restart)}
+              </PlayAreaButton>
+              <PlayAreaButton
+                testId="model-play-capture"
+                label="Capture the viewed player's next frame (std's receiver writes it; the log names the file)"
+                disabled={!playing}
+                onClick={() => { void captureStdView().catch(said('Capture')); }}
+              >
+                {mark(MARKS.capture)}
+              </PlayAreaButton>
+            </>
+          )}
+        </div>
+        {transport && (
+          <div style={{ display: 'flex' }} role="group" aria-label="Game speed">
+            {transport.speeds.map((speed) => (
+              <PlayAreaButton
+                key={speed}
+                testId={`model-play-speed-${speed}`}
+                label={`Speed ${speedText(speed)}`}
+                pressed={clock.speed === speed}
+                wide
+                disabled={documentId === null}
+                onClick={() => { if (documentId !== null) void Promise.resolve(transport.setSpeed(documentId, speed)).catch(said('Speed')); }}
+              >
+                {speedText(speed)}
+              </PlayAreaButton>
+            ))}
+          </div>
+        )}
+        <div style={{ flex: 1 }} />
+        {std === true && <ExportControl />}
+        {/* THE CLOCK IS THE GAME'S, as std answered it: its seconds and frames, still while paused. */}
+        <PlayClockText documentId={documentId} transport={transport} />
+      </div>
+      <div
+        style={{
+          flex: 1,
+          minHeight: 0,
+          display: 'flex',
+          alignItems: 'stretch',
+          gap: TIMELINE_CHROME.headerGap,
+          padding: TIMELINE_CHROME.statusPadding,
+          overflow: 'hidden',
+        }}
+      >
+        <div style={{ flex: '0 1 260px', minWidth: 0, display: 'flex', flexDirection: 'column', gap: 6 }}>
+          <span data-testid="model-play-status" title={status} style={{ whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis' }}>
+            {status}
+          </span>
+          {transport?.autoplay && documentId !== null && (
+            <AutoplayControl documentId={documentId} playing={playing} clock={clock} autoplay={autoplay} transport={transport} />
+          )}
+          {std === true && <ExportNote />}
+        </div>
+        {documentId !== null && <PlayLogView documentId={documentId} />}
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------------------------
+// EXPORT
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * EXPORT, as an engine's editor builds for a platform when it is chosen: a button that opens its menu, the web (`std
+ * build`), or an engine, "Add Roblox and export" where it is not yet one of the game's targets (`std target add`), so a
+ * game is built for an engine only once someone asks for it. A menu, never a select: a stray key on a closed select
+ * changes its value, and a choice here installs packages. Its targets are read afresh as it opens and as an export
+ * ends; while they are unknown, an engine is named plainly and the session decides.
+ */
+function ExportControl() {
+  const { PlayAreaButton, timelineGeometry: { TIMELINE_CHROME, TIMELINE_THEME } } = editorBlender();
+  const current = useSyncExternalStore(onStdExport, stdExport, () => null);
+  const [targets, setTargets] = useState<readonly ExportTarget[] | null>(null);
+  const [open, setOpen] = useState(false);
+  const menu = useRef<HTMLDivElement>(null);
+  const look = useCallback(() => { void stdTargets().then(setTargets, () => setTargets(null)); }, []);
+  const running = current?.running === true;
+  // (read again as an export ends and as another project opens: a project's targets are its own)
+  const project = useSyncExternalStore(onProjectChange, () => getCurrentProject()?.rootPath ?? null, () => null);
+  useEffect(look, [look, running, project]);
+  // (closed by a press outside it or Escape: its buttons keep the keyboard where it was, as the panel's do, so no blur
+  // comes to close it)
+  useEffect(() => {
+    setExportMenuOpen(open);
+    if (!open) return undefined;
+    const outside = (event: PointerEvent): void => { if (!menu.current?.contains(event.target as Node)) setOpen(false); };
+    // (Escape closes the menu alone: the panel's own Escape, which stops the game, never hears it)
+    const escape = (event: KeyboardEvent): void => {
+      if (event.key !== 'Escape') return;
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      setOpen(false);
+    };
+    window.addEventListener('pointerdown', outside, true);
+    window.addEventListener('keydown', escape, true);
+    return () => {
+      setExportMenuOpen(false);
+      window.removeEventListener('pointerdown', outside, true);
+      window.removeEventListener('keydown', escape, true);
+    };
+  }, [open]);
+  const adds = (target: ExportTarget): boolean => target !== 'web' && targets !== null && !targets.includes(target);
+  const choose = (target: ExportTarget): void => {
+    setOpen(false);
+    try { startStdExport(target, adds(target)); } catch (error) { said('Export')(error); }
+  };
+  return (
+    <div ref={menu} style={{ position: 'relative', display: 'inline-flex' }}>
+      <PlayAreaButton
+        testId="model-play-export"
+        label={running && current !== null ? `Exporting to ${EXPORT_LABELS[current.target]}` : 'Export the game: to the web, or to an engine'}
+        pressed={open}
+        wide
+        disabled={running}
+        onClick={() => { if (!open) look(); setOpen(!open); }}
+      >
+        {running ? 'Exporting…' : 'Export'}
+      </PlayAreaButton>
+      {open && (
+        <div
+          role="menu"
+          aria-label="Export to"
+          style={{
+            position: 'absolute', right: 0, top: '100%', marginTop: 4, zIndex: 1,
+            display: 'flex', flexDirection: 'column', minWidth: 170,
+            background: TIMELINE_THEME.header, border: `1px solid ${TIMELINE_CHROME.rule}`, borderRadius: TIMELINE_CHROME.widgetRadius,
+          }}
+        >
+          {EXPORT_TARGETS.map((target) => (
+            <button
+              key={target}
+              type="button"
+              role="menuitem"
+              data-testid={`model-play-export-${target}`}
+              onMouseDown={(event) => event.preventDefault()}
+              onClick={() => choose(target)}
+              style={{ background: 'none', border: 'none', color: TIMELINE_CHROME.text, font: 'inherit', textAlign: 'left', padding: '4px 8px', cursor: 'pointer' }}
+            >
+              {adds(target) ? `Add ${EXPORT_LABELS[target]} and export` : EXPORT_LABELS[target]}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/** THE EXPORT, SAID where the person looks: running with std's last line, or how it ended and where the export is. */
+function ExportNote() {
+  const { timelineGeometry: { TIMELINE_CHROME } } = editorBlender();
+  const current = useSyncExternalStore(onStdExport, stdExport, () => null);
+  if (current === null) return null;
+  const label = EXPORT_LABELS[current.target];
+  const text = exportText(current, label);
+  return (
+    <span
+      data-testid="model-play-export-note"
+      data-export={current.running ? 'running' : current.ok === true ? 'exported' : 'failed'}
+      title={text}
+      style={{ color: TIMELINE_CHROME.widgetText, whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis', minWidth: 0 }}
+    >
+      {text}
+    </span>
+  );
+}
+
+function exportText(current: StdExport, label: string): string {
+  if (current.running) return `Exporting to ${label}${current.line === null ? '…' : ` · ${current.line}`}`;
+  if (current.ok === true) return `Exported to ${label}: ${current.out ?? ''}${current.added ? ` · ${label} added as a target` : ''}`;
+  return `Export to ${label} failed${current.line === null ? '' : `: ${current.line}`} (the console has every line)`;
+}
+
+// ---------------------------------------------------------------------------------------------
+// AUTOPLAY AND THE PLAY LOG
+// ---------------------------------------------------------------------------------------------
+
+function AutoplayControl({ documentId, playing, clock, autoplay, transport }: {
+  readonly documentId: string;
+  readonly playing: boolean;
+  readonly clock: ClockState;
+  readonly autoplay: DocumentPlayAutoplay;
+  readonly transport: DocumentPlayTransport;
+}) {
+  const { PlayAreaButton, timelineGeometry: { TIMELINE_CHROME, TIMELINE_THEME } } = editorBlender();
+  const unavailable = autoplayUnavailable(playing, clock, autoplay);
+  const armed = autoplay.armed === true;
+  // STOPPED, the button ARMS: the next start switches the bot on once its player joins.
+  const canArm = !playing && transport.armAutoplay !== undefined;
+  const label = unavailable === 'game'
+    ? autoplay.unavailable ?? 'No autoplay for the player in view'
+    : unavailable === 'not-running'
+      ? canArm
+        ? armed ? 'Autoplay is armed for the next Play; press to disarm' : 'Let the game’s bot drive your player as soon as it joins'
+        : 'Autoplay is available once a player has joined'
+      : autoplay.on ? 'Stop autoplay and drive yourself' : 'Let the game’s bot drive your player (any key or click in its page takes over)';
+  // SAID, NOT ONLY HOVERED: why there is nothing to switch.
+  const note = unavailable === 'game'
+    ? autoplay.unavailable ?? 'No autoplay for the player in view'
+    : unavailable === 'not-running'
+      ? armed ? 'Armed — turns on once your player joins' : 'Available once a player has joined'
+      : null;
+  // THE GOAL TO PLAY, when the game's bot offers several: chosen here, as `play autoplay on <goal>` names it. Shown
+  // with the one driving (or armed) selected, else the game's own.
+  const goals = autoplay.behaviors ?? [];
+  const [picked, setPicked] = useState<string | null>(null);
+  const goal = autoplay.on || armed ? autoplay.behavior ?? null : picked !== null && goals.includes(picked) ? picked : autoplay.behavior ?? goals[0] ?? null;
+  const driver = driverOf(playing, autoplay);
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: TIMELINE_CHROME.headerGap, minWidth: 0 }}>
+      {goals.length > 1 && (
+        <select
+          data-testid="model-play-autoplay-goal"
+          title="The goal Autoplay's bot plays"
+          value={goal ?? ''}
+          disabled={autoplay.on}
+          onChange={(event) => { setPicked(event.target.value); event.target.blur(); }}
+          style={{ background: TIMELINE_CHROME.widget, color: TIMELINE_CHROME.widgetText, border: 'none', borderRadius: TIMELINE_CHROME.widgetRadius, font: 'inherit', minWidth: 0 }}
+        >
+          {goals.map((name) => <option key={name} value={name}>{name}</option>)}
+        </select>
+      )}
+      {/* The tooltip lives on a wrapper too: a disabled button is the one that most needs it. */}
+      <span title={label} style={{ display: 'inline-flex' }}>
+      {/* KEEP THE KEYBOARD OFF THIS BUTTON (`PlayAreaButton`'s). Left focused, a person taking over with Space would
+          also click this button and turn autoplay straight back on. */}
+      <PlayAreaButton
+        testId="model-play-autoplay"
+        label={label}
+        pressed={autoplay.on || armed}
+        wide
+        disabled={canArm ? false : !playing || unavailable !== null || transport.setAutoplay === undefined}
+        // The switch's state NOW, as the transport's buttons read theirs: a takeover can land between the render and
+        // the click.
+        onClick={() => {
+          const now = transport.autoplay?.(documentId) ?? NO_BOT;
+          try {
+            if (!(extension()?.playing(documentId) ?? false)) transport.armAutoplay?.(documentId, !now.armed, goal ?? undefined);
+            else void Promise.resolve(transport.setAutoplay?.(documentId, !now.on, 'panel', now.on ? undefined : goal ?? undefined)).catch(said('Autoplay'));
+          } catch (error) { said('Autoplay')(error); }
+        }}
+      >
+        Autoplay
+      </PlayAreaButton>
+      </span>
+      {note !== null ? (
+        <span data-testid="model-play-autoplay-note" data-reason={unavailable ?? undefined} style={{ color: TIMELINE_CHROME.widgetText, minWidth: 0 }}>
+          {note}
+        </span>
+      ) : playing && (
+        // WHO DRIVES THE PLAYER IN VIEW, and the goal the bot plays: "Bot driving · collect-all".
+        <span
+          data-testid="model-play-driver"
+          data-driver={driver ?? undefined}
+          style={{ color: autoplay.on ? TIMELINE_THEME.playhead : TIMELINE_CHROME.widgetText, whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis', minWidth: 0 }}
+        >
+          {driver === 'bot' ? `Bot driving${autoplay.behavior ? ` · ${autoplay.behavior}` : ''}` : 'You’re driving'}
+          {autoplay.state ? ` · headless ${autoplay.state}` : ''}
+        </span>
+      )}
+    </div>
+  );
+}
+
+/** Enough to read back what just happened; the whole log is `cyclotron play-log`. */
+const LOG_LINES = 200;
+
+function factsText(facts: Record<string, unknown> | undefined): string {
+  if (facts === undefined) return '';
+  try { return JSON.stringify(facts); } catch { return ''; }
+}
+
+function PlayLogView({ documentId }: { readonly documentId: string }) {
+  const { TIMELINE_CHROME, TIMELINE_THEME } = editorBlender().timelineGeometry;
+  const [kind, setKind] = useState('');
+  // Writes land several to a frame; the view redraws at most once per drawn frame.
+  const [, redraw] = useReducer((count: number) => count + 1, 0);
+  useEffect(() => {
+    let frame = 0;
+    const stop = subscribeModelPlayLog(() => {
+      if (frame === 0) frame = requestAnimationFrame(() => { frame = 0; redraw(); });
+    });
+    return () => { stop(); cancelAnimationFrame(frame); };
+  }, []);
+  const tail = tailModelPlayLog(documentId, LOG_LINES, kind === '' ? undefined : kind);
+  const list = useRef<HTMLDivElement>(null);
+  // Follows the newest entry until the person scrolls up; back at the bottom, it follows again.
+  const following = useRef(true);
+  useLayoutEffect(() => {
+    const element = list.current;
+    if (element && following.current) element.scrollTop = element.scrollHeight;
+  });
+  const newest = tail.entries.at(-1)?.seq;
+  return (
+    <div data-testid="model-play-log" style={{ flex: 1, minWidth: 0, display: 'flex', flexDirection: 'column', gap: 4 }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: TIMELINE_CHROME.headerGap }}>
+        <span>Play log</span>
+        <select
+          data-testid="model-play-log-kind"
+          aria-label="Show entries of kind"
+          value={kind}
+          // Blurred once chosen, so the player's next arrow key moves the game, not this list.
+          onChange={(event) => { setKind(event.target.value); event.target.blur(); }}
+          style={{
+            height: TIMELINE_CHROME.unit,
+            background: TIMELINE_CHROME.widget,
+            color: TIMELINE_CHROME.widgetText,
+            border: `1px solid ${TIMELINE_CHROME.widgetOutline}`,
+            font: 'inherit',
+          }}
+        >
+          <option value="">All kinds</option>
+          {[...new Set([...tail.kinds, ...(kind === '' ? [] : [kind])])].map((one) => <option key={one} value={one}>{one}</option>)}
+        </select>
+        <span style={{ color: TIMELINE_CHROME.widgetText }}>
+          {tail.total === 0 ? 'Nothing logged yet' : `${tail.total} written${tail.total > LOG_LINES ? ` · newest ${LOG_LINES} shown` : ''}`}
+        </span>
+      </div>
+      <div
+        ref={list}
+        data-testid="model-play-log-entries"
+        data-newest={newest}
+        onScroll={(event) => {
+          const element = event.currentTarget;
+          following.current = element.scrollTop + element.clientHeight >= element.scrollHeight - 4;
+        }}
+        style={{
+          flex: 1,
+          minHeight: 0,
+          overflowY: 'auto',
+          font: '12px/1.45 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+          background: TIMELINE_THEME.header,
+          border: `1px solid ${TIMELINE_CHROME.rule}`,
+          padding: '2px 6px',
+        }}
+      >
+        {tail.entries.map((entry) => (
+          <div
+            key={entry.seq}
+            data-kind={entry.kind}
+            style={{ display: 'flex', gap: 10, whiteSpace: 'nowrap', color: entry.source === 'play' ? TIMELINE_CHROME.widgetText : TIMELINE_CHROME.text }}
+          >
+            <span style={{ flex: '0 0 auto', fontVariantNumeric: 'tabular-nums' }}>{clockText(entry.simT)}</span>
+            <span style={{ flex: '0 0 auto' }}>{entry.kind}</span>
+            <span style={{ minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis' }} title={factsText(entry.facts)}>{factsText(entry.facts)}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}