perf(scenes): stop replacing the entire overlay node on each UI change

Right now UIManager is more React-like in data flow, but it still does a full root swap. That’s
acceptable for this small UI, but the cleaner next step would be one of these:

- Keep a stable root and re-render only its children.
  This avoids replacing the mounted DOM subtree and is a better fit if you add more UI state or
  transitions.

I’d keep #ui-overlay mounted once and make only its contents change.

Right now UIManager creates a new root <div id="ui-overlay">...</div> and replaces the old one on each
meaningful UI update. That works, but it means every state change destroys and recreates the whole
overlay subtree, including the button element and any future transition/focus state.

The cleaner version is:

1. Mount a stable root once in the constructor.
   Create this.root = document.createElement('div'), give it the static overlay classes/id, append it to
   document.body, and never replace that node again.
2. Add a dedicated content container inside the root.
   For example this.contentRoot = document.createElement('div') or just render directly into this.root
   if jsx-dom supports replacing children cleanly. The point is that the outer shell stays stable.
3. Compute a pure UI view model in render(state, score).
   Something like:
    - scoreText
    - isScoreVisible
    - panelContent
    - buttonMode
      This isolates game-state mapping from DOM work.
4. Re-render only the children from props.
   GameOverlay becomes a pure presentational component:
    - <GameOverlay scoreText=... isScoreVisible=... panelContent=... onPrimaryAction=... />
      Then UIManager.render(...) clears/replaces the children inside the stable root instead of
      replacing the root itself.
5. Keep callbacks stable.
   The button click handler should still call this.handlePrimaryAction(), and buttonMode stays owned by
   UIManager.

Why this is better:

- #ui-overlay remains mounted, so future transitions, focus handling, and DOM hooks are more reliable.
- The UI still feels React-like because rendering is props-driven.
- UIManager becomes a thin container instead of a DOM mutation class.
- It makes the next step easy: extracting getUIState(...) into a pure function and testing it
  independently.

Author: remarkablemark

src/scenes/ui-manager.tsx

@@ -16,16 +16,25 @@ type OverlayPanelContent = PanelContent & {
  * Lightweight DOM UI for game states and score.
  */
 export class UIManager {
-  private root: HTMLDivElement;
+  private readonly root: HTMLDivElement;
+  private readonly contentRoot: HTMLDivElement;
   private readonly callbacks: UIManagerCallbacks;
   private buttonMode: ButtonMode = 'start';
   private lastRenderedState: GameStateEnum | null = null;
   private lastRenderedScore = Number.NaN;
 
   constructor(callbacks: UIManagerCallbacks) {
     this.callbacks = callbacks;
-    this.root = this.createOverlay('', false, null);
+    this.root = document.createElement('div');
+    this.root.id = 'ui-overlay';
+    this.root.className =
+      'pointer-events-none fixed inset-0 z-2 grid grid-rows-[auto_1fr]';
+
+    this.contentRoot = document.createElement('div');
+    this.contentRoot.className = 'contents';
+    this.root.append(this.contentRoot);
     document.body.append(this.root);
+    this.updateOverlay('', false, null);
   }
 
   /**
@@ -48,13 +57,11 @@ export class UIManager {
       this.buttonMode = panelContent.mode;
     }
 
-    const nextRoot = this.createOverlay(
+    this.updateOverlay(
       `Distance ${String(roundedScore)}m`,
       state !== GameStateEnum.Start,
       panelContent,
     );
-    this.root.replaceWith(nextRoot);
-    this.root = nextRoot;
   }
 
   /**
@@ -113,25 +120,20 @@ export class UIManager {
     return null;
   }
 
-  private createOverlay(
+  private updateOverlay(
     scoreText: string,
     isScoreVisible: boolean,
     panelContent: PanelContent | null,
-  ): HTMLDivElement {
-    return (
-      <div
-        id="ui-overlay"
-        className="pointer-events-none fixed inset-0 z-2 grid grid-rows-[auto_1fr]"
-      >
-        <GameOverlay
-          scoreText={scoreText}
-          isScoreVisible={isScoreVisible}
-          panelContent={panelContent}
-          onPrimaryAction={() => {
-            this.handlePrimaryAction();
-          }}
-        />
-      </div>
-    ) as HTMLDivElement;
+  ): void {
+    this.contentRoot.replaceChildren(
+      <GameOverlay
+        scoreText={scoreText}
+        isScoreVisible={isScoreVisible}
+        panelContent={panelContent}
+        onPrimaryAction={() => {
+          this.handlePrimaryAction();
+        }}
+      />,
+    );
   }
 }