@volter/editor-model-play 0.5.189 → 0.5.191

package/src/model-play.ts

@@ -1,25 +1,125 @@
 /**
- * WHETHER A MODEL DOCUMENT IS PLAYING (the header's Play, `blender-header-menus.tsx`; drawn by
+ * WHETHER A MODEL DOCUMENT IS PLAYING (Play in the Game panel, `blender-game-panel.tsx`; drawn by
  * `blender-runtime.document.tsx`). Playing, the document's area shows a detached copy of the
  * model (`BlenderRuntimeView.detach`) that the project's play script moves
  * (`play-script.ts`); the model, its selection and its history stand as they were, and Stop
  * returns to them. Kept for the page's life and never stored: a reload opens the model, not a
  * game.
+ *
+ * AND HOW ITS CLOCK RUNS. Pause, step, speed and restart are state of the RUN, so they are kept
+ * here beside "is it playing", and the runner (`play-script.ts`) reads them on every frame: the
+ * `dt` a script's `update` receives is the only time a play script is given, so holding it is
+ * what freezes the game and scaling it is what speeds the game up. A script that reads the
+ * page's own clock (`performance.now()`, `Date.now()`) instead is outside that reach.
+ *
+ * AND WHO DRIVES. Autoplay is the editor's switch, not the game's: a script only offers a bot
+ * (`play.autoplay(controller)`, `play-script.ts`), and whether that bot drives is kept here. It
+ * is off whenever a run begins — Play, Restart, Stop — and only the Game panel's toggle or its
+ * verb (`volter.model-play.autoplay`) turns it on. The one carry-over is an ARM: a person may
+ * press Autoplay while stopped (there is no bot yet — a script offers it only once it runs), and
+ * the next start turns autoplay on the moment its script has run its first update with a bot, or
+ * drops the arm if it offers none. The runner turns it off the moment a person
+ * presses a key or touches the game (`takeover`), or when the running script stops offering a
+ * bot (`script`). Its changes are announced through the clock's subscription, which the panel
+ * and the runner already hold.
  */
 const listeners = new Set<() => void>();
+const clockListeners = new Set<() => void>();
 const playing = new Set<string>();
-const stops = new Map<string, (escape: boolean) => void>();
+const stops = new Map<string, { readonly stop: (escape: boolean) => void; readonly generation: number }>();
+
+/** The speeds the transport offers, slowest first (simulation seconds per real second). */
+export const MODEL_PLAY_SPEEDS: readonly number[] = [0.25, 0.5, 1, 2, 4];
+/** The `dt` one Step hands the game: one nominal 60 Hz frame, whatever the speed. */
+export const MODEL_PLAY_STEP_SECONDS = 1 / 60;
+
+export interface ModelPlayClock {
+  readonly time: number;
+  readonly tick: number;
+  readonly paused: boolean;
+  readonly speed: number;
+  /** The run is playing but no game runs: the script failed to start, or threw (`play-script.ts`). */
+  readonly failure: string | null;
+  /** A game has started in this run and runs (`DocumentPlayClock.running`). */
+  readonly running: boolean;
+}
+const STILL: ModelPlayClock = { time: 0, tick: 0, paused: false, speed: 1, failure: null, running: false };
+/** Replaced, never mutated, so a snapshot read by `useSyncExternalStore` changes identity
+ *  exactly when it changes value. */
+const clocks = new Map<string, ModelPlayClock>();
+/** Steps asked for while paused and not yet run; the runner takes one per drawn frame. */
+const steps = new Map<string, number>();
+/** Bumped by Restart; the document keys its detached copy on it (`DocumentPlayTransport`). */
+const generations = new Map<string, number>();
+/** Documents whose next run was begun by Restart, and so enters without the camera's blend. */
+const restarted = new Set<string>();
+
+/** Who last switched autoplay: the panel's toggle, a verb (CLI or `eval`), a person's input
+ *  in the game, or the running script no longer offering a bot (replaced, failed, or its bot
+ *  threw). */
+export type ModelPlayAutoplayBy = 'panel' | 'cli' | 'takeover' | 'script';
+export interface ModelPlayAutoplay {
+  /** The bot drives: its keys are merged into the keys the script reads. */
+  readonly on: boolean;
+  /** The running script registered a bot with `play.autoplay`. */
+  readonly available: boolean;
+  readonly by: ModelPlayAutoplayBy | null;
+  /** Pressed while stopped: the next start turns autoplay on once its script offers a bot. */
+  readonly armed: boolean;
+}
+const NO_BOT: ModelPlayAutoplay = { on: false, available: false, by: null, armed: false };
+const ARMED: ModelPlayAutoplay = { ...NO_BOT, armed: true };
+/** Replaced, never mutated, as the clocks are. Absent is {@link NO_BOT}: a new run's state. */
+const autoplays = new Map<string, ModelPlayAutoplay>();
+
+/** A new run's autoplay: off, no bot yet. Play keeps an arm made while stopped; Stop drops it. */
+function resetAutoplay(documentId: string, keepArm: boolean): void {
+  if (keepArm && modelPlayAutoplay(documentId).armed) autoplays.set(documentId, ARMED);
+  else autoplays.delete(documentId);
+}
+
+function publish(): void {
+  for (const listener of [...listeners]) listener();
+}
+function publishClock(): void {
+  for (const listener of [...clockListeners]) listener();
+}
+function setClock(documentId: string, next: Partial<ModelPlayClock>): void {
+  clocks.set(documentId, { ...modelPlayClock(documentId), ...next });
+  publishClock();
+}
 
 export function modelPlaying(documentId: string): boolean {
   return playing.has(documentId);
 }
 
 export function setModelPlaying(documentId: string, value: boolean): void {
-  if (playing.has(documentId) === value) return;
-  if (!value && stops.has(documentId)) { stops.get(documentId)!(false); return; }
-  if (value) playing.add(documentId);
-  else playing.delete(documentId);
-  for (const listener of [...listeners]) listener();
+  if (playing.has(documentId) === value) {
+    // Stop with nothing playing is how a closing document lets go of its play: an arm made while
+    // stopped goes with it, or reopening the model and pressing Play would still take it.
+    if (!value && modelPlayAutoplay(documentId).armed) { resetAutoplay(documentId, false); publishClock(); }
+    return;
+  }
+  const stop = value ? null : currentStop(documentId);
+  if (stop) { stop(false); return; }
+  if (value) {
+    playing.add(documentId);
+    // A new run starts its clock at zero and running; the speed is the person's and stays.
+    steps.delete(documentId);
+    resetAutoplay(documentId, true);
+    setClock(documentId, { time: 0, tick: 0, paused: false, failure: null, running: false });
+  } else {
+    playing.delete(documentId);
+    restarted.delete(documentId);
+    steps.delete(documentId);
+    resetAutoplay(documentId, false);
+    // The clock keeps the stopped run's time and tick, so the panel still says how far it got.
+    // Re-issued even unchanged, after `playing` has changed: every way a game stops (Stop,
+    // Escape, a deleted script, a mode switch, an agent's `stop`) ends here, and a reader of
+    // the clock alone must see the run end too.
+    setClock(documentId, { paused: false, failure: null, running: false });
+  }
+  publish();
 }
 
 export function finishModelPlay(documentId: string): void {
@@ -28,14 +128,36 @@ export function finishModelPlay(documentId: string): void {
 }
 
 export function escapeModelPlay(documentId: string): void {
-  const stop = stops.get(documentId);
+  const stop = currentStop(documentId);
   if (stop) stop(true);
   else finishModelPlay(documentId);
 }
 
+/**
+ * A RUNNER'S STOP, BOUND TO ITS GENERATION. Stop and Escape go to the runner of the CURRENT
+ * generation, which blends the camera back first; a stop a Restart has superseded is never
+ * asked, because that runner stands still from the moment its generation passes
+ * (`play-script.ts`) and would never finish the blend — the stop would be lost. With no current
+ * runner (a restarted game still preparing) the play simply ends.
+ */
 export function registerModelPlayStop(documentId: string, stop: (escape: boolean) => void): () => void {
-  stops.set(documentId, stop);
-  return () => { if (stops.get(documentId) === stop) stops.delete(documentId); };
+  const entry = { stop, generation: modelPlayGeneration(documentId) };
+  stops.set(documentId, entry);
+  return () => { if (stops.get(documentId) === entry) stops.delete(documentId); };
+}
+
+function currentStop(documentId: string): ((escape: boolean) => void) | null {
+  const entry = stops.get(documentId);
+  return entry !== undefined && entry.generation === modelPlayGeneration(documentId) ? entry.stop : null;
+}
+
+/** The runner's report that no game runs although the run plays (`null` once one does, which
+ *  is also the moment the run is `running`). */
+export function setModelPlayFailure(documentId: string, failure: string | null): void {
+  const clock = modelPlayClock(documentId);
+  const running = failure === null;
+  if (!playing.has(documentId) || (clock.failure === failure && clock.running === running)) return;
+  setClock(documentId, { failure, running });
 }
 
 export function subscribeModelPlay(listener: () => void): () => void {
@@ -44,3 +166,124 @@ export function subscribeModelPlay(listener: () => void): () => void {
     listeners.delete(listener);
   };
 }
+
+export function modelPlayClock(documentId: string): ModelPlayClock {
+  return clocks.get(documentId) ?? STILL;
+}
+
+export function subscribeModelPlayClock(listener: () => void): () => void {
+  clockListeners.add(listener);
+  return () => {
+    clockListeners.delete(listener);
+  };
+}
+
+/** Hold or release the game's updates. Only a playing document has updates to hold. */
+export function setModelPlayPaused(documentId: string, paused: boolean): void {
+  if (!playing.has(documentId) || modelPlayClock(documentId).paused === paused) return;
+  if (!paused) steps.delete(documentId);
+  setClock(documentId, { paused });
+}
+
+/** One update while paused. Steps asked for faster than frames are drawn queue, one per frame,
+ *  so each one is seen. */
+export function stepModelPlay(documentId: string): void {
+  if (!playing.has(documentId) || !modelPlayClock(documentId).paused) return;
+  steps.set(documentId, (steps.get(documentId) ?? 0) + 1);
+}
+
+/** The runner's half of {@link stepModelPlay}: whether this frame runs a step. */
+export function takeModelPlayStep(documentId: string): boolean {
+  const pending = steps.get(documentId) ?? 0;
+  if (pending === 0) return false;
+  if (pending === 1) steps.delete(documentId);
+  else steps.set(documentId, pending - 1);
+  return true;
+}
+
+export function setModelPlaySpeed(documentId: string, speed: number): void {
+  if (!MODEL_PLAY_SPEEDS.includes(speed))
+    throw new Error(`Play speed ${speed} is not one the transport offers: ${MODEL_PLAY_SPEEDS.join(', ')}.`);
+  if (modelPlayClock(documentId).speed !== speed) setClock(documentId, { speed });
+}
+
+/** The runner's report of the updates it ran this frame. */
+export function advanceModelPlayClock(documentId: string, seconds: number, ticks: number): void {
+  if (ticks === 0) return;
+  const clock = modelPlayClock(documentId);
+  setClock(documentId, { time: clock.time + seconds, tick: clock.tick + ticks });
+}
+
+export function modelPlayGeneration(documentId: string): number {
+  return generations.get(documentId) ?? 0;
+}
+
+/**
+ * BEGIN THE RUN AGAIN ON A FRESH COPY. Playing stays true throughout — nothing returns to the
+ * model — and the generation moves, which is what makes the document detach a new copy and mount
+ * a new runner over it; the old runner sees it is no longer the current generation and stands
+ * down without ending the play. A document that is not playing simply starts.
+ */
+export function restartModelPlay(documentId: string): void {
+  if (!playing.has(documentId)) { setModelPlaying(documentId, true); return; }
+  generations.set(documentId, modelPlayGeneration(documentId) + 1);
+  restarted.add(documentId);
+  steps.delete(documentId);
+  // An arm not yet taken (the game was still starting) carries to the fresh run.
+  resetAutoplay(documentId, true);
+  setClock(documentId, { time: 0, tick: 0, paused: false, failure: null, running: false });
+  publish();
+}
+
+/** Whether the run starting now was begun by Restart (asked once, by that run's runner). */
+export function consumeModelPlayRestart(documentId: string): boolean {
+  return restarted.delete(documentId);
+}
+
+export function modelPlayAutoplay(documentId: string): ModelPlayAutoplay {
+  return autoplays.get(documentId) ?? NO_BOT;
+}
+
+function setAutoplay(documentId: string, next: Partial<ModelPlayAutoplay>): void {
+  autoplays.set(documentId, { ...modelPlayAutoplay(documentId), ...next });
+  publishClock();
+}
+
+/** Switch the running script's bot on or off. On asks for a playing document whose script
+ *  registered a bot; off always succeeds, and also drops an arm not yet taken — a person who
+ *  takes over while the game is still starting is driving, and the arm must not override them. */
+export function setModelPlayAutoplay(documentId: string, on: boolean, by: ModelPlayAutoplayBy): void {
+  const now = modelPlayAutoplay(documentId);
+  if (on && !playing.has(documentId))
+    throw new Error(`Autoplay is available once the game is running, and nothing is playing in ${documentId}; \`play\` starts it, then \`play autoplay on\`.`);
+  const clock = modelPlayClock(documentId);
+  if (on && !now.available)
+    throw new Error(clock.running
+      ? 'No autoplay: this game doesn’t provide a bot — its play script registers none with `play.autoplay(controller)`.'
+      : `Autoplay is available once the game is running, and it is not running yet${clock.failure ? ` (${clock.failure})` : ''}.`);
+  if (on ? !now.on : now.on || now.armed) setAutoplay(documentId, on ? { on, by } : { on, by, armed: false });
+}
+
+/** Arm (or disarm) autoplay for the next start, while stopped: the Game panel's Autoplay button
+ *  before Play. Disarming always succeeds. */
+export function armModelPlayAutoplay(documentId: string, armed: boolean): void {
+  if (armed && playing.has(documentId))
+    throw new Error(`${documentId} is already playing; switch autoplay on instead of arming it.`);
+  if (modelPlayAutoplay(documentId).armed !== armed) setAutoplay(documentId, { armed });
+}
+
+/** The runner's report that a script has run its first update, offering a bot or not. An arm is
+ *  taken here: on with a bot, dropped without one. */
+export function settleModelPlayAutoplay(documentId: string, offered: boolean): void {
+  const now = modelPlayAutoplay(documentId);
+  if (!playing.has(documentId)) return;
+  if (!now.armed) { setModelPlayAutoplayAvailable(documentId, offered); return; }
+  setAutoplay(documentId, offered ? { available: true, armed: false, on: true, by: 'panel' } : { available: false, armed: false, by: 'script' });
+}
+
+/** The runner's report of whether the running script offers a bot. Losing it turns autoplay off. */
+export function setModelPlayAutoplayAvailable(documentId: string, available: boolean): void {
+  const now = modelPlayAutoplay(documentId);
+  if (now.available === available || !playing.has(documentId)) return;
+  setAutoplay(documentId, available || !now.on ? { available } : { available, on: false, by: 'script' });
+}

package/src/play-log.ts

@@ -0,0 +1,233 @@
+/**
+ * THE MODEL PLAY LOG — what a play script says happened, stamped with the run's own clock.
+ *
+ * The game editor's play log is the receipt of a run (`play-*.jsonl`, `log-format.ts`); this
+ * is Model Play's. A script calls `play.log(kind, facts)` (`play-script.ts`) on the
+ * transitions that explain a run — a jump, a landing, a death and its cause, autoplay's
+ * choice — and an agent reads them back with `cyclotron play-log` or
+ * `editor.modelPlayLog()` in `eval`. `console.log` cannot do this job: the session's
+ * console feed keeps warnings and errors only.
+ *
+ * Every entry carries `simT` (the seconds of simulation since Play started: the sum of the
+ * `dt`s the runner has handed to `update`) and `tick` (the number of the update in
+ * progress; 0 while the script's default export runs), the same two stamps the game
+ * editor's entries carry. They are the Game panel's clock too: the runner advances both at
+ * the same call (`play-script.ts`), so they stand still while paused and run at the speed. The
+ * runner adds its own lifecycle entries (`source: 'play'`): `play-start`, `play-restart` (a
+ * Restart's fresh run, right after its `play-start`), `script-reload` with its reason,
+ * `script-error`, `tint-unsupported`, `tint-unknown-object`, `pause`, `resume`, `step` (one per
+ * stepped update, with its `dt`), `speed` (on a change, and at a start that is not 1×),
+ * `autoplay-on` and `autoplay-off` (each with `by`: `panel`, `cli`, `takeover`, `script`),
+ * `autoplay-unavailable` (a script ran its first update without offering a bot),
+ * `play-stop`.
+ *
+ * ONE LOG PER MODEL DOCUMENT, each its document's latest run. Two documents playing at once
+ * keep separate logs; a read names its document or takes the active Play's (the latest
+ * started that still plays, else the latest started). Play starting from a fresh copy
+ * replaces its document's log; a script reload does not, and the log outlives Stop so a
+ * finished run can be read. The runner writes through the {@link ModelPlayRun} handle Play
+ * started: once that run has ended its handle writes nothing, so a stale timer of an old
+ * script cannot reach the next run's log.
+ *
+ * BOUNDED AND PAGE-LIFETIME. The newest {@link MODEL_PLAY_LOG_CAPACITY} entries of a run are
+ * kept in a ring (older ones are counted in `dropped`); one entry's facts are kept as JSON of
+ * at most {@link MODEL_PLAY_LOG_FACTS_CHARS} characters. It is never stored: a reload of the
+ * page forgets it, as it forgets the game.
+ *
+ * THE GAME PANEL DRAWS IT LIVE: {@link subscribeModelPlayLog} hears every write, and
+ * {@link tailModelPlayLog} reads the newest entries of one document without copying the ring.
+ *
+ * Logging is a read of the script's own values: it never throws into the script and touches
+ * neither the clock nor the copy.
+ */
+
+/** Entries a run's ring keeps; the oldest beyond this are dropped and counted. */
+export const MODEL_PLAY_LOG_CAPACITY = 5000;
+/** The longest JSON one entry's facts keep; longer facts are kept truncated, as a string. */
+export const MODEL_PLAY_LOG_FACTS_CHARS = 2048;
+
+export interface ModelPlayLogEntry {
+  /** The entry's place in this run, from 0: a gap in `seq` is entries the ring dropped. */
+  readonly seq: number;
+  /** Wall-clock ms. */
+  readonly t: number;
+  /** Seconds of simulation since Play started, across script reloads. */
+  readonly simT: number;
+  /** The update in progress (the first is 1); 0 before the first. */
+  readonly tick: number;
+  readonly kind: string;
+  /** `script` for the play script's own entries; `play` for the runner's lifecycle ones. */
+  readonly source: 'script' | 'play';
+  readonly facts?: Record<string, unknown>;
+}
+
+export interface ModelPlayLogReading {
+  /** The run is still playing; false after Stop, or when nothing has played. */
+  readonly playing: boolean;
+  /** The model document and play script of the run read; null when nothing has played. */
+  readonly documentId: string | null;
+  readonly script: string | null;
+  readonly startedAt: number | null;
+  /** Every model document with a log, so a read can name another. */
+  readonly documents: readonly string[];
+  /** The run's clock now. */
+  readonly simT: number;
+  readonly tick: number;
+  readonly capacity: number;
+  /** Entries this run has written, and how many of those the ring has dropped. */
+  readonly total: number;
+  readonly dropped: number;
+  /** The kept entries that match the read's filters, oldest first. */
+  readonly entries: readonly ModelPlayLogEntry[];
+}
+
+export interface ModelPlayLogQuery {
+  /** The model document whose log to read; the active Play's when omitted. */
+  readonly documentId?: string;
+  /** Only entries at or after this simulation time (seconds). */
+  readonly since?: number;
+  /** Only entries of this kind. */
+  readonly kind?: string;
+}
+
+interface Run {
+  readonly documentId: string;
+  readonly script: string;
+  readonly startedAt: number;
+  playing: boolean;
+  simT: number;
+  tick: number;
+  readonly ring: ModelPlayLogEntry[];
+  total: number;
+  /** Every kind this run has written, for the panel's filter. */
+  readonly kinds: Set<string>;
+}
+
+/** The runner's door onto its own run's log: inert once the run has ended. */
+export interface ModelPlayRun {
+  /** The runner is about to call `update(deltaSeconds)`. */
+  advance(deltaSeconds: number): void;
+  append(source: ModelPlayLogEntry['source'], kind: string, facts?: unknown): void;
+  /** `play-stop`, then nothing more is written; the entries stay readable. */
+  end(facts?: Record<string, unknown>): void;
+}
+
+// One registry per page, whichever copy of this module a contribution loaded it through: the
+// runner writes it from the service, the session verb reads it from the command module.
+const key = Symbol.for('volter.model-play-log');
+const page = globalThis as typeof globalThis & { [key]?: Map<string, Run> };
+const runs: Map<string, Run> = page[key] ??= new Map();
+const listenersKey = Symbol.for('volter.model-play-log.listeners');
+const pageListeners = globalThis as typeof globalThis & { [listenersKey]?: Set<() => void> };
+const listeners: Set<() => void> = pageListeners[listenersKey] ??= new Set();
+
+function publish(): void {
+  for (const listener of [...listeners]) {
+    try { listener(); } catch { /* A reader's failure is not the writer's. */ }
+  }
+}
+
+/** Hear every write to any document's log (several may land in one frame; coalesce). */
+export function subscribeModelPlayLog(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+function keptFacts(facts: unknown): Record<string, unknown> | undefined {
+  if (facts === undefined || facts === null) return undefined;
+  let json: string | undefined;
+  try { json = JSON.stringify(facts); }
+  catch (error) { return { unserializable: error instanceof Error ? error.message : String(error) }; }
+  if (json === undefined) return undefined;
+  if (json.length > MODEL_PLAY_LOG_FACTS_CHARS) return { truncated: json.slice(0, MODEL_PLAY_LOG_FACTS_CHARS) };
+  // A snapshot, so a script that goes on mutating what it logged does not rewrite history.
+  const value: unknown = JSON.parse(json);
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : { value };
+}
+
+function append(run: Run, source: ModelPlayLogEntry['source'], kind: string, facts?: unknown): void {
+  try {
+    const kept = keptFacts(facts);
+    const entry: ModelPlayLogEntry = {
+      seq: run.total, t: Date.now(), simT: run.simT, tick: run.tick, kind: String(kind), source,
+      ...(kept ? { facts: kept } : {}),
+    };
+    run.ring[run.total % MODEL_PLAY_LOG_CAPACITY] = entry;
+    run.total += 1;
+    run.kinds.add(entry.kind);
+  } catch { /* A log that cannot be written is not the script's failure. */ }
+  publish();
+}
+
+/** Play started from a fresh copy: the document's log replaced by an empty one at zero,
+ *  opened by `play-start`. */
+export function beginModelPlayLog(documentId: string, script: string): ModelPlayRun {
+  const run: Run = { documentId, script, startedAt: Date.now(), playing: true, simT: 0, tick: 0, ring: [], total: 0, kinds: new Set() };
+  // Re-inserted, so the map's order is the order Plays started.
+  runs.delete(documentId);
+  runs.set(documentId, run);
+  append(run, 'play', 'play-start', { documentId, script });
+  return {
+    advance(deltaSeconds) {
+      if (!run.playing) return;
+      run.tick += 1;
+      run.simT += deltaSeconds;
+    },
+    append(source, kind, facts) { if (run.playing) append(run, source, kind, facts); },
+    end(facts) {
+      if (!run.playing) return;
+      append(run, 'play', 'play-stop', facts);
+      run.playing = false;
+    },
+  };
+}
+
+function activeRun(): Run | undefined {
+  const started = [...runs.values()].reverse();
+  return started.find((run) => run.playing) ?? started[0];
+}
+
+export function readModelPlayLog(query: ModelPlayLogQuery = {}): ModelPlayLogReading {
+  const run = query.documentId === undefined ? activeRun() : runs.get(query.documentId);
+  const documents = [...runs.keys()];
+  if (!run) {
+    return {
+      playing: false, documentId: query.documentId ?? null, script: null, startedAt: null, documents,
+      simT: 0, tick: 0, capacity: MODEL_PLAY_LOG_CAPACITY, total: 0, dropped: 0, entries: [],
+    };
+  }
+  const dropped = Math.max(0, run.total - MODEL_PLAY_LOG_CAPACITY);
+  const entries: ModelPlayLogEntry[] = [];
+  for (let seq = dropped; seq < run.total; seq++) {
+    const entry = run.ring[seq % MODEL_PLAY_LOG_CAPACITY]!;
+    if (query.since !== undefined && entry.simT < query.since) continue;
+    if (query.kind !== undefined && entry.kind !== query.kind) continue;
+    entries.push(entry);
+  }
+  return {
+    playing: run.playing, documentId: run.documentId, script: run.script, startedAt: run.startedAt, documents,
+    simT: run.simT, tick: run.tick, capacity: MODEL_PLAY_LOG_CAPACITY, total: run.total, dropped, entries,
+  };
+}
+
+export interface ModelPlayLogTail {
+  /** Entries the document's latest run has written; 0 when it has no log. */
+  readonly total: number;
+  /** Every kind that run has written, in the order first seen. */
+  readonly kinds: readonly string[];
+  /** The newest kept entries (of the asked kind), at most `last`, oldest first. */
+  readonly entries: readonly ModelPlayLogEntry[];
+}
+
+/** The newest `last` entries of one document's log, walked from the newest end. */
+export function tailModelPlayLog(documentId: string, last: number, kind?: string): ModelPlayLogTail {
+  const run = runs.get(documentId);
+  if (!run) return { total: 0, kinds: [], entries: [] };
+  const oldest = Math.max(0, run.total - MODEL_PLAY_LOG_CAPACITY);
+  const entries: ModelPlayLogEntry[] = [];
+  for (let seq = run.total - 1; seq >= oldest && entries.length < last; seq--) {
+    const entry = run.ring[seq % MODEL_PLAY_LOG_CAPACITY]!;
+    if (kind === undefined || entry.kind === kind) entries.push(entry);
+  }
+  return { total: run.total, kinds: [...run.kinds], entries: entries.reverse() };
+}