@volter/play 0.5.211 → 0.5.212

package/src/model-play.ts

@@ -1,145 +1,53 @@
 /**
- * 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.
+ * WHETHER A MODEL DOCUMENT IS PLAYING (Play in the Game panel, `contributions/game-panel.tsx`; drawn by
+ * `blender-runtime.document.tsx`). Playing, the document's stage shows the std game's players' pages (`std-game.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 ITS CLOCK, AS STD LAST ANSWERED IT. Pause, step and speed are std's `clock` control on each player's page
+ * (`std-controls.ts`); each answer is the page's clock (`{ paused, speed, time, frame }`), kept here per document
+ * beside whether a game runs and why not, and announced through the clock's own subscription. The speed is the
+ * person's: kept across Plays, and said to each player's page as it joins.
  *
- * 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.
+ * AND AUTOPLAY ARMED WHILE STOPPED: the next start drives the viewed player's bot as its page joins, with the goal it
+ * was armed with (`std-game.ts`). Stop drops the arm.
  */
 const listeners = new Set<() => void>();
 const clockListeners = new Set<() => void>();
 const playing = new Set<string>();
-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). */
+/** The speeds the transport offers, slowest first: std's clock takes 0.25 to 4. */
 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 {
+  /** The viewed player's page's game seconds and frames, as std last answered them. */
   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`). */
+  /** The run is playing but no game runs: its dev server could not start, or no player's page joined. */
   readonly failure: string | null;
-  /** A game has started in this run and runs (`DocumentPlayClock.running`). */
+  /** A player's page has joined this run (`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. */
+/** 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, the running script no longer offering a bot (replaced, failed, or its bot
- *  threw), or the run's time limit. */
-export type ModelPlayAutoplayBy = 'panel' | 'cli' | 'takeover' | 'script' | 'limit';
-/**
- * EVERY AUTOPLAY RUN HAS A LIMIT, in simulation seconds: a bot whose game never ends would
- * otherwise drive forever, and an agent waiting on it would wait forever. Reaching it turns
- * autoplay off, pauses the game and logs `autoplay-limit` (`play-script.ts`).
- */
-export const MODEL_PLAY_AUTOPLAY_LIMIT_SECONDS = 300;
-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;
-  /** The behaviours the running script's bot offers (`play.autoplay({ win, lose })`), in its
-   *  order; a bare function is the one behaviour `play`. */
-  readonly behaviors: readonly string[];
-  /** The behaviour driving now, or armed for the next start. */
-  readonly behavior: string | null;
-  /** This run's limit and the simulation time it began at; null while autoplay is off. */
-  readonly limit: number | null;
-  readonly since: number | null;
-  readonly by: ModelPlayAutoplayBy | null;
-  /** Pressed while stopped: the next start turns autoplay on once its script offers a bot. */
-  readonly armed: boolean;
-  /** A person's key or pointer reached the game in this run. Until one does, nobody drives
-   *  while autoplay is off — the game runs on no input. */
-  readonly person: boolean;
-  /** What the bot last said it is doing (`{ keys, state }` from its controller); kept after
-   *  autoplay goes off, so a limit or takeover still shows where the bot was. */
-  readonly state: string | null;
-  /** Why the last arm was not taken at start (the bot offers no bot, or not the behaviour it asked
-   *  for, or several with none named); null otherwise. Said in the panel and the play log. */
-  readonly refused: string | null;
-}
-/** What a switch-on asks for: the behaviour (required when the bot offers several) and the limit. */
-export interface ModelPlayAutoplayRequest {
-  readonly behavior?: string | null;
-  readonly limit?: number | null;
-}
-const NO_BOT: ModelPlayAutoplay = { on: false, available: false, behaviors: [], behavior: null, limit: null, since: null, by: null, armed: false, person: false, state: null, refused: null };
-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, nobody driving. Play keeps an arm made while stopped
- *  (with the behaviour and limit it asked for); Stop drops it. The behaviours the last run's bot
- *  offered are kept, not available: while stopped they are what the panel's picker offers for an
- *  arm, which is checked against the bot the next start offers. */
-function resetAutoplay(documentId: string, keepArm: boolean): void {
-  const now = modelPlayAutoplay(documentId);
-  if (keepArm && now.armed) autoplays.set(documentId, { ...ARMED, behaviors: now.behaviors, behavior: now.behavior, limit: now.limit });
-  else if (now.behaviors.length) autoplays.set(documentId, { ...NO_BOT, behaviors: now.behaviors });
-  else autoplays.delete(documentId);
-}
-
-/** A limit as given: a positive number of simulation seconds, or the default. */
-function autoplayLimit(limit: number | null | undefined): number {
-  if (limit === undefined || limit === null) return MODEL_PLAY_AUTOPLAY_LIMIT_SECONDS;
-  if (!Number.isFinite(limit) || limit <= 0) throw new Error(`An autoplay limit is a positive number of simulation seconds; got ${String(limit)}.`);
-  return limit;
-}
-
-/** The behaviour a switch-on drives: the one named, which the bot must offer; with none named,
- *  the bot's only behaviour. A bot with several needs one named, so a run always says what its
- *  bot was trying to do. */
-function chosenBehavior(behaviors: readonly string[], named: string | null | undefined): string {
-  if (named) {
-    if (!behaviors.includes(named))
-      throw new Error(`This game's bot has no behaviour "${named}"; it offers ${behaviors.map(b => `"${b}"`).join(', ')}.`);
-    return named;
-  }
-  if (behaviors.length === 1) return behaviors[0]!;
-  throw new Error(`This game's bot offers several behaviours (${behaviors.join(', ')}); name the one to run: \`play autoplay on <behaviour>\`.`);
-}
+/** Autoplay armed while stopped, with the goal it drives (null: the game's own). */
+const arms = new Map<string, { readonly goal: string | null }>();
 
 function publish(): void {
   for (const listener of [...listeners]) listener();
 }
-function publishClock(): void {
+export function publishModelPlayClock(): void {
   for (const listener of [...clockListeners]) listener();
 }
 function setClock(documentId: string, next: Partial<ModelPlayClock>): void {
   clocks.set(documentId, { ...modelPlayClock(documentId), ...next });
-  publishClock();
+  publishModelPlayClock();
 }
 
 export function modelPlaying(documentId: string): boolean {
@@ -148,64 +56,25 @@ export function modelPlaying(documentId: string): boolean {
 
 export function setModelPlaying(documentId: string, value: boolean): void {
   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(); }
+    // Stop with nothing playing is how a closing document lets go of its play: an arm made while stopped goes with it.
+    if (!value && arms.delete(documentId)) publishModelPlayClock();
     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);
+    // A new run's clock starts at zero and running; the speed is the person's and stays.
     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.
+    arms.delete(documentId);
+    // The clock keeps the stopped run's time and frames, so the panel still says how far it got.
     setClock(documentId, { paused: false, failure: null, running: false });
   }
   publish();
 }
 
-export function finishModelPlay(documentId: string): void {
-  stops.delete(documentId);
-  setModelPlaying(documentId, false);
-}
-
-export function escapeModelPlay(documentId: string): void {
-  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 {
-  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`). */
+/** The run's report that no game runs although the run plays (`null` once a player's page joins, 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;
@@ -213,11 +82,23 @@ export function setModelPlayFailure(documentId: string, failure: string | null):
   setClock(documentId, { failure, running });
 }
 
+/** A page's clock as std answered it (`std-controls.ts`'s `StdClock`), kept as the run's. */
+export function setModelPlayClock(documentId: string, clock: { readonly paused: boolean; readonly speed: number; readonly time: number; readonly frame: number }): void {
+  const now = modelPlayClock(documentId);
+  if (now.paused === clock.paused && now.speed === clock.speed && now.time === clock.time && now.tick === clock.frame) return;
+  setClock(documentId, { paused: clock.paused, speed: clock.speed, time: clock.time, tick: clock.frame });
+}
+
+/** The person's speed, kept for the page's life and said to each player's page as it joins. */
+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 });
+}
+
 export function subscribeModelPlay(listener: () => void): () => void {
   listeners.add(listener);
-  return () => {
-    listeners.delete(listener);
-  };
+  return () => { listeners.delete(listener); };
 }
 
 export function modelPlayClock(documentId: string): ModelPlayClock {
@@ -226,45 +107,7 @@ export function modelPlayClock(documentId: string): ModelPlayClock {
 
 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 });
+  return () => { clockListeners.delete(listener); };
 }
 
 export function modelPlayGeneration(documentId: string): number {
@@ -272,105 +115,35 @@ export function modelPlayGeneration(documentId: string): number {
 }
 
 /**
- * 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.
+ * BEGIN THE RUN AGAIN. Playing stays true throughout (nothing returns to the model) and the generation moves, which is
+ * what makes the document detach a new copy and run Play's runner again: every player's page loaded afresh. 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);
+/** Autoplay armed for the next start, and the goal it drives; null when it is not armed. */
+export function modelPlayArm(documentId: string): { readonly goal: string | null } | null {
+  return arms.get(documentId) ?? null;
 }
 
-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, names the behaviour to drive (required when the bot offers several) and
- *  starts the run's limit; 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, request: ModelPlayAutoplayRequest = {}): 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) {
-    const behavior = chosenBehavior(now.behaviors, request.behavior);
-    const limit = autoplayLimit(request.limit);
-    // Switching on again (another behaviour, a new limit) is a new run of the bot.
-    setAutoplay(documentId, { on, by, behavior, limit, since: clock.time, armed: false, state: null, refused: null });
-  } else if (now.on || now.armed) setAutoplay(documentId, { on, by, armed: false, since: null });
-}
-
-/** Arm (or disarm) autoplay for the next start, while stopped: the Game panel's Autoplay button
- *  before Play. The behaviour and limit are checked when the start takes the arm, since the bot
- *  is offered only then. Disarming always succeeds. */
-export function armModelPlayAutoplay(documentId: string, armed: boolean, request: ModelPlayAutoplayRequest = {}): void {
+/** 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, goal: string | null = null): void {
   if (armed && playing.has(documentId))
     throw new Error(`${documentId} is already playing; switch autoplay on instead of arming it.`);
-  if (armed) setAutoplay(documentId, { armed, refused: null, behavior: request.behavior ?? null, limit: request.limit === undefined || request.limit === null ? null : autoplayLimit(request.limit) });
-  else if (modelPlayAutoplay(documentId).armed) setAutoplay(documentId, { armed, behavior: null, limit: null });
-}
-
-/** The runner's report that a script has run its first update, offering a bot's behaviours or
- *  none. An arm is taken here: on with a bot that has the behaviour it asked for (or only one),
- *  dropped otherwise. */
-export function settleModelPlayAutoplay(documentId: string, behaviors: readonly string[]): void {
-  const now = modelPlayAutoplay(documentId);
-  if (!playing.has(documentId)) return;
-  if (!now.armed) { setModelPlayAutoplayAvailable(documentId, behaviors); return; }
-  let behavior: string | null = null;
-  let refused: string | null = null;
-  if (!behaviors.length) refused = 'the play script registers no bot with play.autoplay';
-  else {
-    try { behavior = chosenBehavior(behaviors, now.behavior); }
-    catch (error) { refused = error instanceof Error ? error.message : String(error); }
-  }
-  setAutoplay(documentId, behavior !== null
-    ? { available: true, behaviors, armed: false, on: true, by: 'panel', behavior, limit: now.limit ?? MODEL_PLAY_AUTOPLAY_LIMIT_SECONDS, since: modelPlayClock(documentId).time, state: null, refused: null }
-    : { available: behaviors.length > 0, behaviors, armed: false, behavior: null, limit: null, by: 'script', refused });
-}
-
-/** The runner's report of the behaviours the running script's bot offers (none: no bot). Losing
- *  the bot, or the behaviour driving, turns autoplay off. */
-export function setModelPlayAutoplayAvailable(documentId: string, behaviors: readonly string[]): void {
-  const now = modelPlayAutoplay(documentId);
-  if (!playing.has(documentId)) return;
-  const available = behaviors.length > 0;
-  const same = now.available === available && now.behaviors.length === behaviors.length && now.behaviors.every((b, i) => b === behaviors[i]);
-  if (same) return;
-  const lost = now.on && (now.behavior === null || !behaviors.includes(now.behavior));
-  setAutoplay(documentId, lost ? { available, behaviors, on: false, by: 'script', since: null } : { available, behaviors });
-}
-
-/** The runner's report of what the driving bot says it is doing; announced only when it changes. */
-export function setModelPlayBotState(documentId: string, state: string | null): void {
-  if (playing.has(documentId) && modelPlayAutoplay(documentId).state !== state) setAutoplay(documentId, { state });
+  if (armed) arms.set(documentId, { goal });
+  else if (!arms.delete(documentId)) return;
+  publishModelPlayClock();
 }
 
-/** The runner's report that a person's key or pointer reached the game: from now on in this run,
- *  autoplay off means the person drives. */
-export function noteModelPlayPerson(documentId: string): void {
-  if (playing.has(documentId) && !modelPlayAutoplay(documentId).person) setAutoplay(documentId, { person: true });
+/** The arm taken by the start it was made for. */
+export function takeModelPlayArm(documentId: string): { readonly goal: string | null } | null {
+  const arm = arms.get(documentId) ?? null;
+  if (arm !== null) { arms.delete(documentId); publishModelPlayClock(); }
+  return arm;
 }

package/src/play-clock.ts

@@ -0,0 +1,62 @@
+/**
+ * THE GAME PANEL'S CLOCK, READ AT TWO RATES (`../contributions/game-panel.tsx`).
+ *
+ * The Play tool announces its clock every frame, and one changed text node in the workbench's
+ * document repaints and re-layerizes the page around it (about 4 ms a frame measured), so the
+ * panel does not re-render on every announcement.
+ *
+ * So the panel reads the clock's STATE (paused, speed, failure, running), which changes when a
+ * person or the game changes it and re-renders at once, and its TEXT (time and tick) at most
+ * {@link CLOCK_TEXT_INTERVAL_MS} apart. The text's last change always lands (a trailing update),
+ * so a paused game's step or a stop reads exactly.
+ */
+import type { DocumentPlayClock } from '@volter/editor-blender/api';
+
+/** The clock text's update period: ten times a second, faster than its hundredths can be read. */
+export const CLOCK_TEXT_INTERVAL_MS = 100;
+
+/** `subscribe`, with the listener called at most once per `interval` ms, always after the last
+ *  announcement (trailing). For `useSyncExternalStore`. */
+export function throttledSubscription(
+  subscribe: (listener: () => void) => () => void,
+  interval: number,
+  timers: { set: (run: () => void, ms: number) => unknown; clear: (handle: unknown) => void; now: () => number } = {
+    set: (run, ms) => setTimeout(run, ms),
+    clear: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+    now: () => performance.now(),
+  },
+): (listener: () => void) => () => void {
+  return (listener) => {
+    let pending: unknown = null;
+    let last = -Infinity;
+    const unsubscribe = subscribe(() => {
+      if (pending !== null) return;
+      pending = timers.set(() => {
+        pending = null;
+        last = timers.now();
+        listener();
+      }, Math.max(0, last + interval - timers.now()));
+    });
+    return () => {
+      if (pending !== null) timers.clear(pending);
+      pending = null;
+      unsubscribe();
+    };
+  };
+}
+
+/** The clock's state without its time: what the panel's controls and status line read. */
+export type ClockState = Pick<DocumentPlayClock, 'paused' | 'speed' | 'failure' | 'running'>;
+
+/** A snapshot reader for {@link ClockState} that answers the SAME object until a field changes, so
+ *  `useSyncExternalStore` re-renders only on a change of state, not on every tick. */
+export function clockStateReader(read: () => DocumentPlayClock): () => ClockState {
+  let held: ClockState | null = null;
+  return () => {
+    const clock = read();
+    if (held === null || held.paused !== clock.paused || held.speed !== clock.speed ||
+      (held.failure ?? null) !== (clock.failure ?? null) || held.running !== clock.running)
+      held = { paused: clock.paused, speed: clock.speed, failure: clock.failure ?? null, running: clock.running };
+    return held;
+  };
+}