Throttle what the editor shows while a game runs (#265)

With the behaviors fixed, the scene Performance test still ran at
about 23 fps with 500 entities. The rest of the frame went to the
editor: every spawn or destroy rebuilt the hierarchy with all its
rows, redrew the scene view behind the game tab and refreshed every
panel. The game itself is cheap. What the panels show of it now
follows a preset in the project settings.

- New section While playing in the project settings with three
  presets: Live, Balanced and Minimal. Every project reads as
  Balanced, including those saved before the setting existed.
- Live keeps today's behavior. Balanced brings hierarchy and panel
  values up to date 4 times a second and stops redrawing the hidden
  scene view. Minimal updates hierarchy and values only on pause and
  throttles the graph tabs as well.
- The graph and state machine tabs stay live under Balanced. At 4
  updates a second the beads on exec edges stutter, and the tabs
  draw only while on screen. This differs from the issue proposal.
- The game itself is never throttled. Pause, step and stop bring
  every panel up to date at once, and a change of structure that
  falls between two updates is kept for the next one.
- The rule lives in editor/playThrottle.ts as panelPolicy and
  PanelClock. PlaySession asks it after every frame.
- Objects spawned at the top level go into a hierarchy group named
  after their asset, so hundreds of gold pieces fold into one row.
  Groups start folded.

Measured on a throwaway copy of Performance test, 3 s each, fps:

- About 500 entities: Live 38.6, Balanced 56, Minimal 60.6.
- About 315 entities: Live 56.9, Balanced 60.5, Minimal 60.6.
- p95 frame time at 500 entities: 60 ms, 41 ms and 23 ms.

Tests:

- ./check.sh: 193 files, 2799 tests, CHECK EXIT 0.
- GM_STEPS=1,18,59: ALL PASSED, 54 checks.
- Full e2e run (local): ALL PASSED, 1562 checks.
- tests/editor/play-throttle.test.ts: presets, update rates, kept
  structure changes, flush, spawn group and loading old projects.
- New e2e module 59: preset chosen with the mouse, measured update
  rates, scene view behind the game tab, Minimal with pause.
- Module 03 now expects spawned objects in their group row after the
  next update.
- Counter-checks: 4 in unit tests and 2 in the browser, each failing
  as expected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/editor/ProjectSettingsDialog.ts

@@ -1,13 +1,14 @@
 import { layerFallback, MAX_COLLISION_LAYERS } from '../core/model/collisionLayers';
 import { clampSymbolScale, SYMBOL_SCALE_MAX, SYMBOL_SCALE_MIN } from '../core/model/symbolScale';
 import { Button, HStack, Label, Menu, NumberField, TextField, Theme, VStack } from '../ui';
-import type { PlayFrom } from '../core/model/playSettings';
+import { type PlayFrom, WHILE_PLAYING, type WhilePlaying } from '../core/model/playSettings';
 import { FormDialog } from './FormDialog';
 
 /** What the dialog hands back when Apply is pressed. */
 export interface ProjectSettings {
   name: string;
   playFrom: PlayFrom;
+  whilePlaying: WhilePlaying;
   collisionLayers: string[];
   symbolScale: number;
 }
@@ -22,7 +23,13 @@ export interface ProjectSettings {
 export function settingsChanges(
   before: ProjectSettings,
   after: ProjectSettings,
-): { name?: string; collisionLayers?: string[]; symbolScale?: number; playFrom?: PlayFrom } {
+): {
+  name?: string;
+  collisionLayers?: string[];
+  symbolScale?: number;
+  playFrom?: PlayFrom;
+  whilePlaying?: WhilePlaying;
+} {
   const name = after.name.trim() || before.name;
   const symbolScale = clampSymbolScale(after.symbolScale);
   return {
@@ -32,6 +39,7 @@ export function settingsChanges(
       : { collisionLayers: [...after.collisionLayers] }),
     ...(symbolScale === before.symbolScale ? {} : { symbolScale }),
     ...(after.playFrom === before.playFrom ? {} : { playFrom: after.playFrom }),
+    ...(after.whilePlaying === before.whilePlaying ? {} : { whilePlaying: after.whilePlaying }),
   };
 }
 
@@ -40,8 +48,15 @@ const PLAY_FROM_LABEL: Record<PlayFrom, string> = {
   active: 'Active scene',
 };
 
+const WHILE_PLAYING_LABEL: Record<WhilePlaying, string> = {
+  live: 'Live',
+  balanced: 'Balanced',
+  minimal: 'Minimal',
+};
+
 /**
- * Everything about the project that is not an asset (#183): its name, which scene Play starts, the
+ * Everything about the project that is not an asset (#183): its name, which scene Play starts and
+ * how closely the panels follow it (#265), the
  * size of the scene view's symbol icons, and the collision layers (#152). The top bar carries icons
  * only, so this is the one place they are edited.
  *
@@ -52,10 +67,12 @@ const PLAY_FROM_LABEL: Record<PlayFrom, string> = {
 export class ProjectSettingsDialog extends FormDialog {
   private projectName: string;
   private playFrom: PlayFrom;
+  private whilePlaying: WhilePlaying;
   private layers: string[];
   private symbolScale: number;
   private readonly nameField: TextField;
   private readonly playFromButton: Button;
+  private readonly whilePlayingButton: Button;
   private readonly symbolScaleField: NumberField;
   private readonly rows = new VStack({ gap: Theme.gap });
   private readonly addButton: Button;
@@ -64,6 +81,7 @@ export class ProjectSettingsDialog extends FormDialog {
     super(340, 'Project settings');
     this.projectName = settings.name;
     this.playFrom = settings.playFrom;
+    this.whilePlaying = settings.whilePlaying;
     this.layers = [...settings.collisionLayers];
     this.symbolScale = clampSymbolScale(settings.symbolScale);
 
@@ -88,6 +106,18 @@ export class ProjectSettingsDialog extends FormDialog {
       }),
     );
 
+    this.whilePlayingButton = new Button(WHILE_PLAYING_LABEL[this.whilePlaying], {
+      width: 150,
+      align: 'left',
+      onClick: () => this.openWhilePlayingMenu(),
+    });
+    this.content.add(this.formRow(this.fieldLabel('While playing'), this.whilePlayingButton));
+    this.content.add(
+      new Label('How often the panels follow a game: every frame, 4 times a second, or on pause.', {
+        style: 'muted',
+      }),
+    );
+
     this.symbolScaleField = new NumberField(this.symbolScale, {
       width: 150,
       min: SYMBOL_SCALE_MIN,
@@ -122,6 +152,7 @@ export class ProjectSettingsDialog extends FormDialog {
       onApply({
         name: this.projectName,
         playFrom: this.playFrom,
+        whilePlaying: this.whilePlaying,
         collisionLayers: this.layers,
         symbolScale: this.symbolScale,
       }),
@@ -134,9 +165,14 @@ export class ProjectSettingsDialog extends FormDialog {
     return [...this.layers];
   }
 
-  /** Name, start-scene switch and symbol scale as they stand (test hook). */
-  values(): { name: string; playFrom: PlayFrom; symbolScale: number } {
-    return { name: this.projectName, playFrom: this.playFrom, symbolScale: this.symbolScale };
+  /** Name, start-scene switch, panel preset and symbol scale as they stand (test hook). */
+  values(): { name: string; playFrom: PlayFrom; whilePlaying: WhilePlaying; symbolScale: number } {
+    return {
+      name: this.projectName,
+      playFrom: this.playFrom,
+      whilePlaying: this.whilePlaying,
+      symbolScale: this.symbolScale,
+    };
   }
 
   /** The start-scene switch itself, so a check can click it. */
@@ -144,6 +180,11 @@ export class ProjectSettingsDialog extends FormDialog {
     return this.playFromButton;
   }
 
+  /** The panel preset switch, so a check can click it. */
+  get whilePlayingControl(): Button {
+    return this.whilePlayingButton;
+  }
+
   /** The symbol scale field, so a check can type into it. */
   get symbolScaleControl(): NumberField {
     return this.symbolScaleField;
@@ -170,6 +211,19 @@ export class ProjectSettingsDialog extends FormDialog {
     new Menu([entry('start'), entry('active')]).openBelow(this.playFromButton);
   }
 
+  private openWhilePlayingMenu(): void {
+    new Menu(
+      WHILE_PLAYING.map((mode) => ({
+        label: WHILE_PLAYING_LABEL[mode],
+        current: this.whilePlaying === mode,
+        onSelect: () => {
+          this.whilePlaying = mode;
+          this.whilePlayingButton.setText(WHILE_PLAYING_LABEL[mode]);
+        },
+      })),
+    ).openBelow(this.whilePlayingButton);
+  }
+
   private addLayer(): void {
     if (this.layers.length >= MAX_COLLISION_LAYERS) return;
     this.layers.push(layerFallback(this.layers.length));