@volter/editor-model-play 0.5.189 → 0.5.191

package/src/play-script.ts

@@ -22,6 +22,34 @@
  * The tool blends the camera from the editing pose for 0.8 seconds after
  * update, holding keys empty until arrival. Stop freezes the copy and blends
  * back before disposing it; Escape during either blend completes that blend.
+ *
+ * THE GAME'S TIME IS THE `dt` IT IS HANDED, and the runner decides it (`model-play.ts` keeps
+ * the run's clock): paused, `update` is not called at all and the camera holds the last drawn
+ * pose; a Step is one `update` of one nominal frame; a speed scales the frame's seconds, and a
+ * scaled frame longer than a tenth of a second is run as several updates so the promise below —
+ * at most a tenth per call — holds at 4× too. The camera's own blends run on the page's time,
+ * because they are the editor's motion and not the game's. Restart is the document detaching a
+ * fresh copy for a new runner (`restartModelPlay`); this runner, no longer the current
+ * generation, stands down without ending the play.
+ *
+ * THE PLAY LOG KEEPS THE SAME CLOCK (`play-log.ts`): the run's log is advanced by exactly the
+ * `dt` of each `update` the panel's clock counts, at the same call, so an entry's `simT` and
+ * `tick` are the numbers the Game panel shows. A Restart is a fresh copy and so a fresh log,
+ * opened by `play-start` and then `play-restart`; pause, resume, each step and a speed change
+ * are lifecycle entries of their own.
+ *
+ * AUTOPLAY IS THE GAME'S BOT AND THE EDITOR'S SWITCH. A script offers one bot,
+ * `play.autoplay(controller)`: a plain function the runner calls before each `update` while
+ * autoplay is on, handed that update's `dt`, `simT`, `tick` and the keys the person holds, and
+ * answering the keys the bot holds. The runner merges those into `keys` for that update, so the
+ * bot drives through the script's own input code, exactly as a person's keys do. Whether it
+ * drives is not the script's to say (`model-play.ts`): off at every Play and Restart, on only
+ * from the Game panel or its verb, and off again the moment a person presses a key the game
+ * would hear or presses a pointer in the game — before that key reaches `keys`. A synthetic key
+ * (`editor.document.key`) is dispatched as a DOM event like a person's and is handled as one;
+ * the bot's own keys never pass through the DOM, so they cannot take over from themselves. The
+ * controller is called only here, inside the editor's runner: a game run anywhere else never
+ * drives itself.
  */
 import { editorHost } from '@volter/editor-sdk/host';
 import { getCurrentProject } from '@volter/editor-sdk/kit/active-project';
@@ -38,7 +66,24 @@ import type * as THREE from 'three';
 import { projectPlayLayers } from '@volter/editor-sdk/kit/project-play-layers';
 import { beginProjectMountEpoch, projectEntryImportUrl } from '@volter/editor-sdk/session/project-module-url';
 import { cameraTransition } from './camera-transition';
-import { finishModelPlay, registerModelPlayStop } from './model-play';
+import {
+  advanceModelPlayClock,
+  consumeModelPlayRestart,
+  finishModelPlay,
+  MODEL_PLAY_STEP_SECONDS,
+  modelPlayAutoplay,
+  modelPlayClock,
+  modelPlayGeneration,
+  registerModelPlayStop,
+  setModelPlayAutoplay,
+  setModelPlayFailure,
+  setModelPlayAutoplayAvailable,
+  settleModelPlayAutoplay,
+  subscribeModelPlayClock,
+  takeModelPlayStep,
+} from './model-play';
+import { beginModelPlayLog } from './play-log';
+import { materialOverrides } from './play-materials';
 interface PlayComposition {
   readonly entries: readonly string[];
   loadScript(): Promise<{ default?: unknown }>;
@@ -58,14 +103,97 @@ export interface ModelPlayContext {
   readonly camera: THREE.Camera;
   /** The keys held now, by `KeyboardEvent.code` (`ArrowUp`, `KeyW`, `Space`). */
   readonly keys: ReadonlySet<string>;
+  /**
+   * Write one entry to the play log, stamped with the run's simulation time and frame
+   * (`play-log.ts`): a kind and the facts that explain it, JSON-serialisable and snapshotted
+   * now. Log transitions (a landing, a death and its cause, autoplay's choice), not every
+   * frame. Read back with `cyclotron play-log [--since <simT>] [--kind <k>] [--json]`
+   * or `editor.modelPlayLog({ since, kind })` in `eval`. Never throws, never changes the game,
+   * and does nothing once this script has been replaced or Play has stopped.
+   *
+   *     play.log('death', { cause: 'lava', at: player.position, stage });
+   */
+  log(kind: string, facts?: Record<string, unknown>): void;
+  /**
+   * Draw an object and the meshes under it in `color` (a `THREE.Color`, `'#2bff6b'`,
+   * `0x2bff6b`); an emitting surface glows in it too, an image texture is multiplied by it.
+   * `null` returns the authored colours. Other objects wearing the same Blender material keep
+   * theirs. An object is a name or one `find` answered.
+   *
+   * THE PRESENTED MATERIALS, which is why this exists: a mesh's `material` is an array with
+   * one shared `MeshPhysicalMaterial` per Blender material slot (a lone material only for an
+   * object without slots), so `material.color` is undefined, and editing an entry recolours
+   * every object wearing that Blender material. The presenter re-assigns those slots
+   * whenever it re-applies shading, `clone()` drops its shader hooks, and a node graph
+   * driving Base Color or Alpha ignores `color` and `opacity`. A tinted or faded object
+   * wears copies of its own slots, drawn from their constant inputs (a node graph's
+   * other inputs are not drawn while it does), and keeps them through a script reload. An
+   * object with a material the document cannot copy (one the script made) is left as it is,
+   * and the log says so once with a `tint-unsupported` entry.
+   */
+  tint(object: THREE.Object3D | string, color: THREE.ColorRepresentation | null): void;
+  /** Fade an object and the meshes under it to `opacity` (0 to 1); `null` returns the
+   *  authored opacity. Its colour is untouched, and the copies are `tint`'s. */
+  setOpacity(object: THREE.Object3D | string, opacity: number | null): void;
+  /**
+   * Offer this game's bot. While the person (or an agent, `play autoplay on`) has autoplay on in
+   * the Game panel, `controller` is called before each `update` and the keys it answers are held
+   * for that update, merged into `keys`. Autoplay is off at every Play and Restart, and a
+   * person's key or pointer in the game turns it off. One bot per script: registering again
+   * replaces it, `null` withdraws it, and it goes with the script. Never bind autoplay to a game
+   * key, and never start it from the script.
+   *
+   *     play.autoplay(({ dt }) => (car.speed < 20 ? ['ArrowUp'] : []));
+   */
+  autoplay(controller: ModelPlayAutoplayController | null): void;
+}
+
+/** What the bot is handed before each `update` it drives. */
+export interface ModelPlayAutoplayInput {
+  /** The `dt` the coming `update` is handed. */
+  readonly dt: number;
+  /** Simulation seconds and the update's number, as that update's log entries carry them. */
+  readonly simT: number;
+  readonly tick: number;
+  /** The keys the person holds, by `KeyboardEvent.code`; the bot's are merged with them. */
+  readonly keys: ReadonlySet<string>;
 }
+/** A game's bot: the keys (`KeyboardEvent.code`) it holds for the coming update. */
+export type ModelPlayAutoplayController = (input: ModelPlayAutoplayInput) => Iterable<string> | null | undefined;
 
 export interface ModelPlayGame {
-  /** Once per drawn frame, with the seconds since the last one (at most a tenth). */
+  /** Once per drawn frame, with the simulation seconds since the last call (at most a tenth).
+   *  Not called while the game is paused; called once per Step; at a speed other than 1× the
+   *  seconds are scaled, and a fast frame may call it more than once. */
   update(deltaSeconds: number): void;
   dispose?(): void;
 }
 
+/** One script's lifetime: `value` until it is replaced, fails or the run stops; `bot` is what it
+ *  offered `play.autoplay`; `unknown` the object names it asked for that the model lacks, each
+ *  logged once — per script, so a typo that survives a reload is said again for the new one. */
+interface Script {
+  value: boolean;
+  bot: ModelPlayAutoplayController | null;
+  readonly unknown: Set<string>;
+}
+
+/** The longest `dt` one update is handed; longer scaled frames are split (`frameUpdates`). */
+const MAX_UPDATE_SECONDS = 0.1;
+
+/**
+ * THE UPDATES THIS DRAWN FRAME RUNS, as the `dt` each is handed: none while paused, one nominal
+ * frame for a Step, and otherwise the frame's seconds times the speed, split into equal parts of
+ * at most {@link MAX_UPDATE_SECONDS}.
+ */
+function frameUpdates(documentId: string, frameSeconds: number): number[] {
+  const clock = modelPlayClock(documentId);
+  if (clock.paused) return takeModelPlayStep(documentId) ? [MODEL_PLAY_STEP_SECONDS] : [];
+  const scaled = frameSeconds * clock.speed;
+  const parts = Math.max(1, Math.ceil(scaled / MAX_UPDATE_SECONDS - 1e-9));
+  return Array.from({ length: parts }, () => scaled / parts);
+}
+
 /** The play script's project path for a model's `.blend`. */
 export function playScriptPath(blend: string): string {
   return blend.replace(/\.blend$/i, '') + '.play.ts';
@@ -107,14 +235,77 @@ export function runPlayScript(options: {
   readonly container: HTMLElement;
   readonly ready: () => void;
   readonly returning: () => void;
+  readonly ownMaterial?: ((material: THREE.Material) => THREE.Material | null) | undefined;
 }): () => void {
-  const { blend, root, camera, onFrame, report } = options;
+  const { blend, root, camera, onFrame } = options;
   const modulePath = playScriptPath(blend);
+  // A fresh copy is a fresh run: its log starts empty, its clock at zero. Writes go through
+  // this run's handle, which is inert once the run has ended.
+  const run = beginModelPlayLog(options.documentId, modulePath);
+  const report = (phase: 'start' | 'update' | 'stop' | 'autoplay', title: string, error: unknown): void => {
+    const detail = error instanceof Error ? error.message : String(error);
+    run.append('play', 'script-error', { phase, message: detail });
+    // NO GAME RUNS NOW (a first start that failed, or the running game threw): the run still
+    // plays, and a save retries it, but what is on screen is not a game. Said on the clock, so
+    // the Game panel can say so and the document drops a Restart's cover (`failure`).
+    if ((phase === 'start' || phase === 'update') && game === null && current())
+      setModelPlayFailure(options.documentId, `${title}: ${detail}`);
+    options.report(title, detail);
+  };
+  // Said once per object: a script that tints every frame would otherwise fill the log.
+  const unsupported = new WeakSet<THREE.Mesh>();
+  const materials = materialOverrides({
+    root,
+    ownMaterial: options.ownMaterial,
+    unsupported: (mesh, material) => {
+      if (unsupported.has(mesh)) return;
+      unsupported.add(mesh);
+      run.append('play', 'tint-unsupported', { object: mesh.name, material: material.name,
+        why: options.ownMaterial ? 'the material is not one the document presents' : 'this document lends no material copies' });
+    },
+  });
+  // An unknown name is the script's typo, not a reason to stop its game: said once per name, per script.
+  const objectOf = (script: Script, target: THREE.Object3D | string, call: 'tint' | 'setOpacity'): THREE.Object3D | null => {
+    if (typeof target !== 'string') return target;
+    const object = root.getObjectByName(target) ?? null;
+    if (!object && !script.unknown.has(target)) {
+      script.unknown.add(target);
+      run.append('play', 'tint-unknown-object', { object: target, call });
+    }
+    return object;
+  };
   const keys = new Set<string>();
   const heldKeys = new Set<string>();
-  const transition = cameraTransition(options.editingCamera());
+  // The run this runner belongs to. A Restart moves the document to the next generation, whose
+  // own runner takes over; this one must then stand down without ending the play.
+  const generation = modelPlayGeneration(options.documentId);
+  const current = (): boolean => modelPlayGeneration(options.documentId) === generation;
+  const restarted = consumeModelPlayRestart(options.documentId);
+  const transition = cameraTransition(options.editingCamera(), { instant: restarted });
+  // THE TRANSPORT'S CHANGES, IN THE LOG. Pause, resume and speed are the person's (or an
+  // agent's) calls on `model-play.ts`, between frames; this run notes each as it lands. A run
+  // that Restart has replaced notes nothing more — its successor's log has the restart.
+  let seen = modelPlayClock(options.documentId);
+  let seenBot = modelPlayAutoplay(options.documentId);
+  if (restarted) run.append('play', 'play-restart', { speed: seen.speed });
+  else if (seen.speed !== 1) run.append('play', 'speed', { speed: seen.speed });
+  const stopClock = subscribeModelPlayClock(() => {
+    const now = modelPlayClock(options.documentId);
+    if (!current()) return;
+    if (now.paused !== seen.paused) run.append('play', now.paused ? 'pause' : 'resume');
+    if (now.speed !== seen.speed) run.append('play', 'speed', { speed: now.speed, from: seen.speed });
+    seen = now;
+    const bot = modelPlayAutoplay(options.documentId);
+    if (bot.on !== seenBot.on) run.append('play', bot.on ? 'autoplay-on' : 'autoplay-off', { by: bot.by });
+    // An arm dropped before it was taken: a takeover, or a script that offers no bot. (Stop's
+    // reset has no `by`, and its `play-stop` says enough.)
+    else if (seenBot.armed && !bot.armed && bot.by !== null) run.append('play', 'autoplay-off', { by: bot.by, armed: true });
+    seenBot = bot;
+  });
   options.container.style.opacity = '0';
-  const context: ModelPlayContext = {
+  /** One script's context: its log, tint, opacity and bot do nothing once that script is gone
+   *  (replaced, failed, or the run stopped), so a stale timer cannot reach a later one. */
+  const contextFor = (alive: Script): ModelPlayContext => ({
     root,
     find(name) {
       const object = root.getObjectByName(name) ?? null;
@@ -126,7 +317,22 @@ export function runPlayScript(options: {
       return camera();
     },
     keys,
-  };
+    log(kind, facts) { if (alive.value) run.append('script', kind, facts); },
+    tint(object, color) {
+      const target = alive.value ? objectOf(alive, object, 'tint') : null;
+      if (target) materials.tint(target, color);
+    },
+    setOpacity(object, opacity) {
+      const target = alive.value ? objectOf(alive, object, 'setOpacity') : null;
+      if (target) materials.setOpacity(target, opacity);
+    },
+    autoplay(controller) {
+      if (controller !== null && typeof controller !== 'function')
+        throw new Error('play.autoplay takes a function (the bot) or null.');
+      if (alive.value) alive.bot = controller;
+    },
+  });
+  const scripts = new WeakMap<ModelPlayGame, Script>();
   let stopped = false;
   let attempt = 0;
   let game: ModelPlayGame | null = null;
@@ -153,8 +359,13 @@ export function runPlayScript(options: {
   const dispose = (ending: ModelPlayGame | null, layers: PlayComposition | null): void => {
     try { ending?.dispose?.(); }
     catch (error) {
-      report(`${modulePath} failed while stopping`, error instanceof Error ? error.message : String(error));
-    } finally { layers?.dispose(); }
+      report('stop', `${modulePath} failed while stopping`, error);
+    } finally {
+      // After its own dispose, which may still log; nothing it scheduled may.
+      const alive = ending && scripts.get(ending);
+      if (alive) { alive.value = false; alive.bot = null; }
+      layers?.dispose();
+    }
   };
   const end = (): void => {
     dispose(game, composition);
@@ -163,10 +374,12 @@ export function runPlayScript(options: {
     if (startedAt !== null) endedAt = Date.now();
     live.notifyChanged();
   };
-  const start = async (): Promise<void> => {
+  /** `reload` says why a replacement mounts, for the log's `script-reload`; null for Play's first start. */
+  const start = async (reload: { readonly reason: string; readonly path: string } | null): Promise<void> => {
     const mine = ++attempt;
     if (pending) { dispose(pending.game, pending.composition); pending = null; }
     let nextComposition: PlayComposition | undefined;
+    const alive: Script = { value: true, bot: null, unknown: new Set() };
     try {
       if (mountLayers) {
         const project = getCurrentProject();
@@ -191,26 +404,42 @@ export function runPlayScript(options: {
         };
       }
       if (stopped || mine !== attempt) { nextComposition?.dispose(); return; }
-      const next = await startGame(modulePath, context, nextComposition);
+      // Before the replacement's default export runs, so what it logs follows this.
+      if (reload) run.append('play', 'script-reload', reload);
+      const next = await startGame(modulePath, contextFor(alive), nextComposition);
+      scripts.set(next, alive);
       if (stopped || mine !== attempt) {
         dispose(next, nextComposition ?? null);
         return;
       }
       pending = { game: next, composition: nextComposition ?? null };
     } catch (error) {
+      alive.value = false;
       nextComposition?.dispose();
       if (stopped || mine !== attempt) return;
-      report(`${modulePath} did not start`, error instanceof Error ? error.message : String(error));
+      report('start', `${modulePath} did not start`, error);
     }
   };
   let firstFrame = true;
+  /** Whether the last script to run its first update offered a bot (null before any did), so
+   *  `autoplay-unavailable` is said once per run, and again only after a bot came and went. */
+  let offeredBot: boolean | null = null;
   let returning = false;
+  let stopReason = 'stop';
   const stopRequest = registerModelPlayStop(options.documentId, (escape) => {
+    if (escape) stopReason = 'escape';
     keys.clear();
     heldKeys.clear();
     if (firstFrame || transition.stop(escape)) finishModelPlay(options.documentId);
   });
   const stopFrames = onFrame((deltaSeconds) => {
+    // REPLACED BY A RESTART, and not yet unmounted: the document keeps this copy on screen until
+    // the new one has drawn, so it stands as it is — no update, no clock, the camera held.
+    if (!current()) {
+      if (game !== null) transition.hold(camera());
+      keys.clear();
+      return;
+    }
     if (transition.leaving()) {
       options.container.style.opacity = String(transition.hudOpacity());
       if (!returning && transition.approachingEdit()) { returning = true; options.returning(); }
@@ -220,41 +449,137 @@ export function runPlayScript(options: {
     if (!surfaceHoldsKeyboard()) { keys.clear(); heldKeys.clear(); }
     else if (!transition.acceptingKeys()) keys.clear();
     else for (const key of heldKeys) keys.add(key);
-    let replacementUpdated = false;
+    // The panel's toggle is enabled by the bot the running script offers, as of the last frame.
+    if (current()) setModelPlayAutoplayAvailable(options.documentId, game !== null && scripts.get(game)?.bot != null);
+    const updates = frameUpdates(options.documentId, deltaSeconds);
+    if (updates.length === 0) {
+      // PAUSED: no update, so nothing states the camera; hold the pose the last frame drew.
+      // A pending replacement waits too — its first update is a tick of the game's time.
+      // A tap made while paused is dropped; a key still held is seen by the next step.
+      if (game !== null) transition.hold(camera());
+      keys.clear();
+      return;
+    }
+    // Each update is counted — by the panel's clock and the log alike — as it is CALLED, so an
+    // update that throws still took its tick, in both.
+    let ran = 0;
+    let simulated = 0;
+    // THE BOT'S KEYS, per update: the person's keys of this frame and what the bot holds now. It
+    // drives only once the camera has arrived, as a person's keys reach the game only then.
+    const clock = modelPlayClock(options.documentId);
+    const driving = current() && modelPlayAutoplay(options.documentId).on && transition.acceptingKeys();
+    const person: ReadonlySet<string> = driving ? new Set(keys) : keys;
+    /** `keys` back to the person's alone. Only ever after `drive` has added the bot's, when
+     *  `person` is a copy — never `keys` itself. */
+    const restorePerson = (): void => {
+      keys.clear();
+      for (const key of person) keys.add(key);
+    };
+    /** Merge the bot's keys into `keys` for one update; true when it did, and the caller then
+     *  restores the person's keys after that update, however it ends. */
+    const drive = (script: ModelPlayGame, dt: number): boolean => {
+      const bot = driving ? scripts.get(script)?.bot : null;
+      // Asked again per update: the bot's own failure, a takeover, or `play.autoplay(null)`
+      // ends it mid-frame.
+      if (!bot || !modelPlayAutoplay(options.documentId).on) return false;
+      restorePerson();
+      try {
+        for (const key of bot({ dt, simT: clock.time + simulated, tick: clock.tick + ran, keys: person }) ?? []) keys.add(String(key));
+        return true;
+      } catch (error) {
+        restorePerson();
+        setModelPlayAutoplay(options.documentId, false, 'script');
+        report('autoplay', `${modulePath}'s autoplay failed`, error);
+        return false;
+      }
+    };
+    /** One update, bot-driven or not. The bot's keys hold for this update only: restored in a
+     *  `finally`, so neither a bot withdrawn mid-frame, nor an update that throws, nor a reloaded
+     *  script leaves them reading as held. */
+    const update = (script: ModelPlayGame, dt: number): void => {
+      tick(dt);
+      const driven = drive(script, dt);
+      try { script.update(dt); }
+      finally { if (driven) restorePerson(); }
+    };
+    // A paused frame that runs an update is a Step; its entry carries the step's own tick.
+    const stepping = modelPlayClock(options.documentId).paused;
+    const tick = (dt: number): void => {
+      run.advance(dt);
+      ran += 1;
+      simulated += dt;
+      if (stepping) run.append('play', 'step', { dt });
+    };
+    // A replacement's first update takes the frame's first slot whether it starts or throws; a
+    // running game that a failed replacement leaves in place runs the rest of the frame.
+    let firstSlot = 0;
     if (pending) {
+      firstSlot = 1;
       const next = pending;
       pending = null;
       try {
-        next.game.update(deltaSeconds);
+        update(next.game, updates[0]!);
         end();
         game = next.game;
+        // NOW THE SCRIPT HAS SAID WHETHER IT OFFERS A BOT (its default export and first update
+        // are where `play.autoplay` is called): said before `running`, so no reader sees a running
+        // game with its bot not yet counted, and an arm made while stopped is taken or dropped.
+        const offered = scripts.get(next.game)?.bot != null;
+        if (!offered && offeredBot !== false)
+          run.append('play', 'autoplay-unavailable', { why: 'the play script registers no bot with play.autoplay(controller)' });
+        offeredBot = offered;
+        // A KEY THE PERSON ALREADY HOLDS is a takeover the runner did not hear: it was pressed while
+        // the stage was still preparing, before these listeners existed, and has only repeated
+        // since. The person is driving, so an arm waiting for this update is dropped.
+        if (heldKeys.size > 0 && modelPlayAutoplay(options.documentId).armed) takeover();
+        settleModelPlayAutoplay(options.documentId, offered);
+        setModelPlayFailure(options.documentId, null);
         startedAt = Date.now();
         endedAt = null;
         composition = next.composition;
         live.notifyChanged();
         composition?.reveal();
-        replacementUpdated = true;
       } catch (error) {
         dispose(next.game, next.composition);
-        report(`${modulePath} did not start`, error instanceof Error ? error.message : String(error));
+        report('start', `${modulePath} did not start`, error);
       }
     }
-    if (game === null) return;
+    if (game === null) { advanceModelPlayClock(options.documentId, simulated, ran); keys.clear(); return; }
     try {
-      if (!replacementUpdated) game.update(deltaSeconds);
+      for (let index = firstSlot; index < updates.length; index++) {
+        update(game, updates[index]!);
+      }
+      advanceModelPlayClock(options.documentId, simulated, ran);
+      ran = 0;
       transition.frame(camera(), deltaSeconds);
       options.container.style.opacity = String(transition.hudOpacity());
       if (firstFrame) { firstFrame = false; options.ready(); }
     } catch (error) {
+      advanceModelPlayClock(options.documentId, simulated, ran);
+      keys.clear();
       end();
-      report(`${modulePath} failed`, error instanceof Error ? error.message : String(error));
+      report('update', `${modulePath} failed`, error);
       return;
     }
+    materials.frame();
     keys.clear();
     root.updateMatrixWorld(true);
   });
+  // THE PERSON ALWAYS WINS: a new key press the game would hear, or a pointer pressed anywhere
+  // in the game's area (its HUD included), hands control back before the input is the game's.
+  // Untrusted events count: `editor.document.key` and the probe's clicks are how an agent plays
+  // by hand.
+  const surface = options.container.parentElement ?? options.container;
+  const takeover = (): void => {
+    // An arm still waiting for the bot counts too: the person is driving before it could start.
+    const now = modelPlayAutoplay(options.documentId);
+    if (current() && (now.on || now.armed)) setModelPlayAutoplay(options.documentId, false, 'takeover');
+  };
   const onKeyDown = (event: KeyboardEvent): void => {
     if (!surfaceAcceptsKey(event)) return;
+    // A repeat is a key already held, not a new press — unless this runner never saw it go down:
+    // then it was pressed before the runner was listening, and that press was a takeover.
+    if (!event.repeat || !heldKeys.has(event.code)) takeover();
     heldKeys.add(event.code);
     if (transition.acceptingKeys()) keys.add(event.code);
   };
@@ -262,7 +587,11 @@ export function runPlayScript(options: {
     // Preserve a between-frame tap until one game update has observed it.
     heldKeys.delete(event.code);
   };
+  const onPointerDown = (event: PointerEvent): void => {
+    if (event.target instanceof Node && surface.contains(event.target)) takeover();
+  };
   const onBlur = (): void => { keys.clear(); heldKeys.clear(); };
+  window.addEventListener('pointerdown', onPointerDown, true);
   window.addEventListener('keydown', onKeyDown, true);
   window.addEventListener('keyup', onKeyUp, true);
   window.addEventListener('blur', onBlur);
@@ -272,26 +601,33 @@ export function runPlayScript(options: {
     // would manufacture a mount failure while the old game is still alive.
     // A missing dependency continues through the ordinary error-reporting path.
     if (type === 'delete' && projectModuleChangeMatches(changed, modulePath)) {
+      stopReason = 'script-deleted';
       finishModelPlay(options.documentId);
       return;
     }
     // A composed HUD and script must remount together, including shared-store
     // edits. A fresh epoch is threaded to both through the UI tool door.
     const entries = [modulePath, ...retryEntries, ...(composition?.entries ?? []), ...(pending?.composition?.entries ?? [])];
-    if ([changed, ...(affected ?? [])].some(path => entries.some(entry => projectModuleChangeMatches(path, entry)))) void start();
+    if ([changed, ...(affected ?? [])].some(path => entries.some(entry => projectModuleChangeMatches(path, entry))))
+      void start({ reason: type === 'delete' ? 'dependency-deleted' : 'saved', path: changed });
   });
-  void start();
+  void start(null);
   return () => {
     stopped = true;
     unregisterLive();
     stopRequest();
-    finishModelPlay(options.documentId);
+    // A runner replaced by Restart leaves the play running for its successor.
+    if (current()) finishModelPlay(options.documentId);
     stopFrames();
+    stopClock();
     stopChanges();
+    window.removeEventListener('pointerdown', onPointerDown, true);
     window.removeEventListener('keydown', onKeyDown, true);
     window.removeEventListener('keyup', onKeyUp, true);
     window.removeEventListener('blur', onBlur);
     if (pending) { dispose(pending.game, pending.composition); pending = null; }
     end();
+    materials.dispose();
+    run.end({ reason: stopReason });
   };
 }