@volter/play 0.5.211 → 0.5.213

package/contributions/game-panel.tsx

@@ -0,0 +1,807 @@
+/**
+ * THE GAME PANEL — Play, the project's, in editor-blender's bottom area: under every document, and below a model in its
+ * Game mode, where its Animation mode shows Blender's Timeline instead (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").
+ *
+ * ## Where it is
+ *
+ * play registers it through editor-blender's API (`registerPlay`, `play.page.tsx`); the area's own Game | Animation
+ * switch below a model and its size stay the area's. It draws with the area's button and the Timeline's widget table.
+ * The game itself shows in the Game view (`../src/game-view.tsx`), which Play opens.
+ *
+ * ## What it drives is the game's run
+ *
+ * Every control here is a call on the run (`../src/game-run.ts`, `../src/game-controls.ts`), 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.play.<verb>`), which is how an agent drives exactly what the person does: `cyclotron play pause`, or
+ * `await editor.command('volter.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.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 (`../src/play-log.ts`): its newest entries, 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 ReactNode,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+import { editorBlender } 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 { GAME_SPEEDS, gameClock, type GameClock, gamePlaying, subscribeGame, subscribeGameClock } from '../src/game-run';
+import {
+  armAutoplay,
+  type GameAutoplay,
+  gameAutoplay,
+  pauseGame,
+  playGame,
+  restartPlay,
+  setGameAutoplay,
+  setGameSpeedOf,
+  stepGame,
+  subscribeGameControls,
+} from '../src/game-controls';
+import { captureStdView, isStdGame, MOST_PLAYERS, setStdPlayers, STD_DEV, stdPlayersAsked, stepStdPlayers, stdRun, stdRunVersion, subscribeStdGame, subscribeStdRun } from '../src/std-game';
+import { EXPORT_LABELS, EXPORT_TARGETS, isExportTarget, onStdExport, startStdExport, stdExport, stdTargets, type ExportTarget, type StdExport } from '../src/std-export';
+import { subscribePlayLog, tailPlayLog } from '../src/play-log';
+import { showGameView } from '../src/game-view';
+
+/** 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.';
+
+/** The bottom area's mode and the model document it serves: editor-blender's, through its API. */
+const playMode = () => editorBlender().playMode;
+
+// ---------------------------------------------------------------------------------------------
+// THE VERBS — `volter.play.<verb>`, the panel's controls behind command ids.
+// ---------------------------------------------------------------------------------------------
+
+/** The model document a mode verb acts on: the one in front, whose bottom area is its Game or Animation. */
+function modelInFront(): string {
+  const served = playMode().servedModelDocument();
+  if (served === null) throw new Error('No model document is in front: Game | Animation is a model\'s bottom area.');
+  return served;
+}
+
+/** 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(): unknown {
+  const model = playMode().servedModelDocument();
+  return {
+    // (a model in front has Game or Animation; any other document, the Game panel)
+    mode: model === null ? 'game' : playMode().modelPlayMode(model),
+    playing: gamePlaying(),
+    script: { path: STD_DEV, exists: isStdGame() ?? null },
+    clock: gameClock(),
+    speeds: GAME_SPEEDS,
+    autoplay: autoplayState(),
+    // (a std game's: how many players Play starts, and how many have joined the running game)
+    ...(isStdGame() === true ? { players: { asked: stdPlayersAsked(), joined: stdRun()?.players.length ?? 0 } } : {}),
+    export: stdExport(),
+  };
+}
+
+/** Who drives the player in view: the bot while std's play drives its page, else the person. */
+function driverOf(playing: boolean, autoplay: GameAutoplay): 'bot' | 'person' | null {
+  if (!playing) return null;
+  return autoplay.driving === true ? '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(): unknown {
+  const autoplay = gameAutoplay();
+  const playing = gamePlaying();
+  const why = autoplayWhy(playing, gameClock(), 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<GameClock, 'failure' | 'running'>, autoplay: GameAutoplay): '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<GameClock, 'failure' | 'running'>, autoplay: GameAutoplay): 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(verb: string): void {
+  if (!gamePlaying()) throw new Error(`Nothing is playing, so there is nothing to ${verb}; \`play\` starts it.`);
+}
+
+/** The Game panel's verbs: the Code-OSS commands `volter.play.<verb>`, registered by play's page half. */
+export const PLAY_VIEW_VERBS: readonly ViewVerb[] = [
+  { id: 'state', run: () => gameState() },
+  {
+    id: 'mode',
+    run: (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(modelInFront(), asked);
+      }
+      return gameState();
+    },
+  },
+  {
+    // HOW MANY PLAY: a std game's player count, the project's setting (`volter.play.players`); a running game's players
+    // join or leave to match it.
+    id: 'players',
+    run: async (args) => {
+      const raw = args?.['players'] ?? args?.['count'];
+      if (raw !== undefined) {
+        if (isStdGame() !== true) throw new Error('players is a std game\'s player count; this project is not a std game.');
+        const count = typeof raw === 'string' && raw.trim() !== '' ? Number(raw) : typeof raw === 'number' ? raw : Number.NaN;
+        if (!Number.isInteger(count) || count < 1 || count > 8) throw new Error(`players is a whole number from 1 to 8; got ${JSON.stringify(raw)}.`);
+        // (answered once the setting is in force)
+        await setStdPlayers(count);
+      }
+      return gameState();
+    },
+  },
+  {
+    id: 'game-mode',
+    run: () => { editorBlender().switchPlayMode(modelInFront(), 'game'); return gameState(); },
+  },
+  {
+    id: 'animation-mode',
+    run: () => { editorBlender().switchPlayMode(modelInFront(), 'animation'); return gameState(); },
+  },
+  {
+    // (the game played in the Game view, brought to the front where it already plays, as Play opens it)
+    id: 'play',
+    run: () => {
+      if (!gamePlaying()) playGame(true);
+      else showGameView();
+      return gameState();
+    },
+  },
+  { id: 'stop', run: () => { playGame(false); return gameState(); } },
+  {
+    id: 'pause',
+    run: async () => {
+      requirePlaying('pause');
+      await pauseGame(true);
+      return gameState();
+    },
+  },
+  {
+    id: 'resume',
+    run: async () => {
+      requirePlaying('resume');
+      await pauseGame(false);
+      return gameState();
+    },
+  },
+  {
+    // `count` frames of 1/60 s, which std runs (pausing the game first) and answers.
+    id: 'step',
+    run: async (args) => {
+      requirePlaying('step');
+      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 stepGame(count);
+      return gameState();
+    },
+  },
+  {
+    id: 'speed',
+    run: async (args) => {
+      const raw = args?.['speed'] ?? args?.['to'];
+      const speed = typeof raw === 'string' ? Number(raw.replace(/x$/i, '')) : Number(raw);
+      if (!GAME_SPEEDS.includes(speed))
+        throw new Error(`speed is one of ${GAME_SPEEDS.join(', ')} (game seconds per real second); got ${JSON.stringify(raw)}.`);
+      await setGameSpeedOf(speed);
+      return gameState();
+    },
+  },
+  {
+    // THE EDITOR'S AUTOPLAY SWITCH: on plays one of the game's goals (`goal`, the game's own when absent), off ends
+    // that play, handing a page it drives back to the person. From here (an agent's `cli`) as from the panel, the goal is std's own play,
+    // recorded and checked, on the viewed player's page while the Game view is on screen and on std's headless device
+    // while it is not (`setStdAutoplay`): 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 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;
+      // (refused while nothing plays; the run says its own reasons, a headless play needing no player's page)
+      if (on && !gamePlaying()) throw new Error(autoplayWhy(false, gameClock(), gameAutoplay()) ?? 'Nothing is playing.');
+      await setGameAutoplay(on, 'cli', on ? goal : undefined);
+      return gameState();
+    },
+  },
+  {
+    id: 'restart',
+    run: () => {
+      restartPlay();
+      return gameState();
+    },
+  },
+  {
+    // 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() {
+  const { TIMELINE_CHROME } = editorBlender().timelineGeometry;
+  const subscribe = useMemo(() => throttledSubscription(subscribeGameClock, CLOCK_TEXT_INTERVAL_MS), []);
+  const text = useSyncExternalStore(
+    subscribe,
+    () => {
+      const clock = gameClock();
+      const playing = gamePlaying();
+      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="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)}`, 'play');
+
+export function GamePanel() {
+  const { PlayAreaButton, PlayModeSwitch, timelineGeometry: { HEADER_HEIGHT, TIMELINE_CHROME, TIMELINE_THEME } } = editorBlender();
+  const { subscribePlayMode, playModeVersion } = playMode();
+  useSyncExternalStore(subscribePlayMode, playModeVersion, playModeVersion);
+  // (the project's run, whatever document is in front)
+  const playing = useSyncExternalStore(subscribeGame, gamePlaying, () => false);
+  // 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(gameClock), []);
+  const clock = useSyncExternalStore(subscribeGameClock, readClockState, readClockState);
+  // Whether the project is a std game, which Play plays (undefined while the session is asked).
+  const std = useSyncExternalStore(subscribeStdGame, isStdGame, () => undefined);
+  const autoplay = useSyncExternalStore(subscribeGameControls, gameAutoplay, gameAutoplay);
+  const scriptPath = STD_DEV;
+  // 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 asked = stdPlayersAsked();
+  const thrown = playing ? stdRun()?.lastError ?? null : null;
+  // (std's own play of a goal, where it stands: `win: achieved`, `lose: failed — why`)
+  const headlessLine = playing && autoplay.state ? ` · ${autoplay.state}` : '';
+  const status = std === false
+      ? NOT_STD
+      : playing && clock.failure
+        // The run plays but no game runs (`GameClock.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}` + headlessLine
+        : `Stopped · Play runs ${scriptPath}`;
+  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="play-button"
+            label={playing ? 'Stop the game' : 'Play the game'}
+            pressed={playing}
+            wide
+            // The run's state NOW, not the render's: a game can stop between the two (an agent's `stop`, the Game view
+            // closed, a failed script), and a toggle read from a stale render does nothing.
+            onClick={() => { playGame(!gamePlaying()); }}
+          >
+            {mark(playing ? MARKS.stop : MARKS.play)}
+            {playing ? 'Stop' : 'Play'}
+          </PlayAreaButton>
+          <PlayAreaButton
+            testId="play-pause"
+            label={clock.paused ? 'Resume' : 'Pause'}
+            pressed={playing && clock.paused}
+            disabled={!playing}
+            onClick={() => { void pauseGame(!gameClock().paused).catch(said('Pause')); }}
+          >
+            {mark(clock.paused ? MARKS.play : MARKS.pause)}
+          </PlayAreaButton>
+          <PlayAreaButton
+            testId="play-step"
+            label="Step one frame (pauses first)"
+            disabled={!playing}
+            onClick={() => { void stepGame().catch(said('Step')); }}
+          >
+            {mark(MARKS.step)}
+          </PlayAreaButton>
+          <PlayAreaButton
+            testId="play-restart"
+            label="Restart: the level saved, every player's page loaded again"
+            disabled={!playing}
+            onClick={() => { restartPlay(); }}
+          >
+            {mark(MARKS.restart)}
+          </PlayAreaButton>
+          <PlayAreaButton
+            testId="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>
+        {std === true && (
+          // HOW MANY PLAY, beside Play as an engine's Play settings are: set before a run, and a running game's
+          // players join or leave to match. A refused write is said on the console.
+          <div style={{ display: 'flex', alignItems: 'center' }} role="group" aria-label="Players">
+            <span style={{ padding: '0 4px' }}>Players</span>
+            <PlayAreaButton testId="std-players-remove" label="One player fewer (a running game's last player leaves)" disabled={asked <= 1} onClick={() => { stepStdPlayers(-1).catch(() => {}); }}>
+              −
+            </PlayAreaButton>
+            <span data-testid="std-players-count" style={{ minWidth: 14, textAlign: 'center' }}>{asked}</span>
+            <PlayAreaButton testId="std-players-add" label="One more player (a running game's new player joins)" disabled={asked >= MOST_PLAYERS} onClick={() => { stepStdPlayers(1).catch(() => {}); }}>
+              +
+            </PlayAreaButton>
+          </div>
+        )}
+        <div style={{ display: 'flex' }} role="group" aria-label="Game speed">
+          {GAME_SPEEDS.map((speed) => (
+            <PlayAreaButton
+              key={speed}
+              testId={`play-speed-${speed}`}
+              label={`Speed ${speedText(speed)}`}
+              pressed={clock.speed === speed}
+              wide
+              onClick={() => { void setGameSpeedOf(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 />
+      </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="play-status" title={status} style={{ whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis' }}>
+            {status}
+          </span>
+          <AutoplayControl playing={playing} clock={clock} autoplay={autoplay} />
+          {std === true && <ExportNote />}
+        </div>
+        <PlayLogView />
+      </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(() => {
+    if (!open) return undefined;
+    const outside = (event: PointerEvent): void => { if (!menu.current?.contains(event.target as Node)) setOpen(false); };
+    // (Escape closes the menu alone)
+    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 () => {
+      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="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={`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="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({ playing, clock, autoplay }: {
+  readonly playing: boolean;
+  readonly clock: ClockState;
+  readonly autoplay: GameAutoplay;
+}) {
+  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;
+  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 ? (autoplay.driving === true ? 'Stop autoplay and drive yourself' : 'Stop the bot’s play of its goal')
+        : '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="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="play-autoplay"
+        label={label}
+        pressed={autoplay.on || armed}
+        wide
+        disabled={canArm ? false : !playing || unavailable !== null}
+        // 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 = gameAutoplay();
+          try {
+            if (!gamePlaying()) armAutoplay(now.armed !== true, goal ?? undefined);
+            else void setGameAutoplay(!now.on, 'panel', now.on ? undefined : goal ?? undefined).catch(said('Autoplay'));
+          } catch (error) { said('Autoplay')(error); }
+        }}
+      >
+        Autoplay
+      </PlayAreaButton>
+      </span>
+      {note !== null ? (
+        <span data-testid="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="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.state ? ` · ${autoplay.behavior}` : ''}` : 'You’re driving'}
+          {autoplay.state ? ` · ${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() {
+  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 = subscribePlayLog(() => {
+      if (frame === 0) frame = requestAnimationFrame(() => { frame = 0; redraw(); });
+    });
+    return () => { stop(); cancelAnimationFrame(frame); };
+  }, []);
+  const tail = tailPlayLog(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="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="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="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>
+  );
+}